# Documentation

## Re-design

1. Top level module folder has suffix `-v2` (reporting-v2, common-v2)
2. All new files should not import anything from **v1**, except `backend-api`
3. **constants**, **utils**, **helpers**, etc. that are needed for **v2** - should be moved to **v2** folders

## Installation

1. `.env.shadow` should be copied to `.env.development` to start work
2. Env variables to enable authorization should be requested privately
   - `USE_OLD_AUTH=true` (to switch Frontend to Auth0 login)
   - `AUTH_STRATEGY=auth0` (to switch Backend to Auth0 login)
3. **yarn install** install dependencies
4. Add `127.0.0.1 local.decibel.stream` to the `/etc/hosts`
   1. Open terminal
   2. `sudo nano /etc/hosts` (will ask you for the password)
   3. Add `127.0.0.1 local.decibel.stream` line
   4. Press `control + O` to save the file
   5. Press `control + X` to exit the nano editor
5. **sudo yarn start** (will ask you for the password) run the frontend
6. Go to https://local.decibel.stream (process with unsecure)
7. **sh start_dev.sh** (inside backend folder) run the backend

## Dependencies

##### Unsafe to update

1. **auth0-lock** (11.22.2)
2. **highcharts** (9.0.1)
3. **highcharts-react-official** (2.2.2)

## Architecture Guidelines

#### 1. Module

- Page or component shared across the project are module
- Module has its own state and functionality
- Module can and should be lazy loaded

#### 2. Module folder structure

##### /containers

- Folder to keep container components
- Container components have to do with how things work.
- They may contain presentational components.
- Provides data and behavior to presentational components and other container components.
- Because they are mostly data sources, they are often stateful.

##### /components

- Folder to keep presentational components
- Presentational components are primarily concerned with how things look.
- Most times they contain no more than a render method.
- Presentational components do not know how to load or alter the data that they render.
- Presentational components rarely have any internally changeable state properties.
- Presentational components best written as stateless functional components.
- Presentational components don’t directly contain container components.
- Presentational components should not declare containers, but can receive them as props/children.

##### /components/component

- Folder to keep presentational component files
- `/component/index.ts` exports jsx and all stuff related to the component needed to use it
- `/component/component.tsx` component itself
- `/component/s-component.ts` styled component (css styles) for the component

##### /hooks

- Folder to keep all custom hooks belong to this module

##### /selectors.ts

- File to keep simple selectors which just returns createSelector
- createStructuredSelector function from 'reselect' should be used in containers
- Links to read: https://medium.com/@parkerdan/react-reselect-and-redux-b34017f8194c
- About makeSelector() syntax https://blog.isquaredsoftware.com/2017/12/idiomatic-redux-using-reselect-selectors/
- About createStructuredSelector() https://github.com/reduxjs/reselect#createstructuredselectorinputselectors-selectorcreator--createselector

##### /actions.ts

- File to keep all actions

##### /reducer.ts

- Reducer follows ducks modular architecture https://github.com/erikras/ducks-modular-redux

##### /epics.ts

- File to keep all API request and following logic

##### /transducers.ts

- Pure functions (mappers) which only transform one data structure into another
- All algorythms and data manipulations should be here.
- Not in components! Not in selectors!

##### /constants.ts

- File to keep all constants which belong to this module

##### /types.ts

- File to keep shared types of this module

#### 3. /app

Is the main module where all modules are combined.
Redux store is setup here. Ideally app module shouldn't have own reducer

- Redux setup here
- Root reducers are configured here
- Root epics are here
- This module shouldn't have its own reducer - it's only to combine all app modules
- Theme provider for styled components is configured here
- Global styles are inside /s-components/s-global-styles
- Persist gate and localStorage connection
- Application routing is inside routing.tsx

#### 4. /common

Is to keep all shared among the app functionality
Ideally all general application logic should be inside common reducer.
This module will not be code splitted.

- `/utils` folder contains all helper not specific to project
- `/utils/api-rx` and `utils/api` Api service (1-st rx.js based, 2-nd promised based)
- `/containers/dynamic-form` incapsulates redux-form setup
- `/components/form` `Field` component - to build redux forms

#### 5. /auth

Folder responds for everything related to authorization

#### 6. /assets

Contains static files and `index.ejs` - the main template

## Styling

- All colors, common typography, shadows and other common styles should be used from theme
- [Styled Components for styling](https://styled-components.com/)
- Each presentational component that needs styles should have its own root styled component (just one)
- Inside styled component all classes follows BEM methodology
- Each new class or pseudo element have to be separated by new line
- CSS mixins or helpers should be placed before all other css properties
- Styled component should export `BEM_CLASS` in case of nested classes usage
- If just styled component needed it can be created inside `/styled` folder in a root of module
- Component root styles should not have properties that have outside effect

## Assets

#### SVG

There is two way of importing svgs, as file and raw html

- `<img src={require('./file.svg')} />`
- `import File from './file.raw.svg';` `<File />`

If you need to inject svg into inline sprite you can use this way

- `import File from './file.sprite.svg';`
- ```
    <svg viewBox={File.viewBox}>
      <use xlinkHref={`#${File.id}`} />
    </svg>
  ```

## Code template generator

Is used to generate entities in the application https://plopjs.com/

- `yarn gen component` to start generating tempalate (component in this case)
- All generators ar inside `/plop` folder
- `/plop/generators` to describe new generators
- `/plop/templates` to create new templates for generators

## Serve locally build folder

We must have possibility to debug our application after build locally.
Also we could edit already built files to see the difference.
Serve command will start the application on localhost:3000.
This port is important because some 3-rd party services rely on the exact
port.

##### First run

- `cd ./proxy/server`
- `yarn install`

##### Second run

- `yarn build`
- frontend root folder
- `yarn serve`

##### In case you have docker installed

- `yarn build`
- `yarn docker` - to serve build folder with localhost:5000 as a proxy
- Don't forget to shut down the docker container after you finish

## Unit tests

#### 1.General

Usually we write unit tests for **selectors**, **reducers** and **transducers**

#### 2. Commands

- `yarn test` - run tests
- `yarn test:gui` - open majestic gui for jest

## Git

#### 1. General

- Separate subject from the body with a blank line
- Limit the subject line to 50 characters
- Summary in the present tense. Not capitalized.
- Do not end the subject line with a period
- Use the imperative mood in the subject line
- Wrap the body at 72 characters
- Use the body to explain what and why vs. how

#### 2. Branch types

- **build** - Build related changes
- **ci** - CI related changes
- **chore** - Build process or auxiliary tool changes
- **docs** - Documentation only changes
- **feature** - A new feature
- **fix** - A bug fix
- **perf** - A code change that improves performance
- **refactor** - A code change that neither fixes a bug or adds a feature
- **revert** - Reverting things
- **style** - Markup, white-space, formatting, missing semi-colons...
- **test** - Adding missing tests

#### 3. Branch names

```
feature/DEC-1234
fix/DEC-1234
refactor/artist-component
test/project-reducer
```

#### 4. Commit messages

Pattern - `[<jira tickets>](<additional info>): <subject>`

```
[DEC-1234]: Implement data dictionary; initial schemas versions
[DEC-1234, DEC-1234]: Fix artist page bugs
[DEC-1234](WIP): Add linkfire funnel chart on project page
```