docs: Add authentication, configuration and visualization information

README.md

 # 🏠 Home
 
-[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
-[![pipeline status](https://gitlab.com/sibmip/gateway/badges/main/pipeline.svg)](https://gitlab.com/sibmip/gateway/-/commits/main)
+[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release) [![pipeline status](https://gitlab.com/sibmip/gateway/badges/main/pipeline.svg)](https://gitlab.com/sibmip/gateway/-/commits/main)
 
 ## Introduction
 
-The MIP Gateway is a middleware layer between the [MIP Frontend](https://github.com/HBPMedical/portal-frontend) and a federate analytic engine (Exareme, Datashield, FATE, MedCo, etc...).
+The MIP Gateway is a middleware layer between the [MIP Frontend](https://github.com/HBPMedical/portal-frontend) and a federate analytic engine (Exareme, Datashield, etc...).
 
 ## Contact
-* [Manuel Spuhler](https://github.com/nicedexter) (<manuel.spuhler@chuv.ch>)
-* [Steve Mendes Reis](https://github.com/M4n0x) (<steve.mendes-reis@chuv.ch>)
 
-## Technical documentation 
-
-Technical documentation can be found at [https://mip-front.gitbook.io/mip-gateway-doc/](https://mip-front.gitbook.io/mip-gateway-doc/)
+* [Manuel Spuhler](https://github.com/nicedexter) ([manuel.spuhler@chuv.ch](mailto:manuel.spuhler@chuv.ch))
+* [Steve Mendes Reis](https://github.com/M4n0x) ([steve.mendes-reis@chuv.ch](mailto:steve.mendes-reis@chuv.ch))
 
+## Technical documentation
 
+Technical documentation can be found at [https://mip-front.gitbook.io/mip-gateway-doc/](https://mip-front.gitbook.io/mip-gateway-doc/)

SUMMARY.md

@@ -7,7 +7,11 @@
 * [Get Started](docs/for-developers/get-started/README.md)
   * [Introduction](docs/get-started/Introduction.md)
   * [Setup development environment](docs/get-started/Setup-development-environment.md)
-* [Connector](docs/for-developers/connector/README.md)
+* [Configuration](for-developers/configuration/README.md)
+  * [Gateway](for-developers/configuration/gateway.md)
+* [Connectors](docs/for-developers/connector/README.md)
   * [Parsing response with JSONdata](docs/gateway/Connector/Parsing-response-with-JSONata.md)
+* [Authentication](for-developers/authentication.md)
 * [Frontend](docs/for-developers/frontend/README.md)
   * [Update GraphQL Queries](docs/frontend/Update-queries-GrahpQL-in-the-frontend.md)
+  * [Visualisations](for-developers/frontend/visualisations.md)

docs/frontend/Update-queries-GrahpQL-in-the-frontend.md

 # Update GraphQL Queries
 
-## New method
-
-The context of the this page is related to the portal-frontend not the gateway directly.
-
-In order to update or create new types and operations, you can proceed with the following command :
-
-```bash
-yarn codegen
-```
-
-This command will generate all the operations and types for you. You should place the graphql's operations in the file queries.ts under the folder `src/components/API/GraphQL`. Types will be all generated in one file under the name `types.generated.ts`, operations will be in `queries.generated.tsx` file and all fragments under the file `fragments.generated.tsx`.
-
-***
-
-## Previous method
-
-This method is no more needed as the front-portal has been updated and all the commands can be made on the front directly.
-
-### Context
-
-_(This guide mainly follow the procedure describe here : https://blog.logrocket.com/build-graphql-react-app-typescript/)_
-
-This guide is made to generate types and hooks to query/mutate for the frontend based on the GraphQL API. This tool is used to avoid to do it manually.
-
-The generation could be made directly from the frontend project but due to the old dependencies in the current frontend project it does not work.
-
-The guide, that will be describe here, is a workaround to generate the types/hooks outside of the front project.
-
-### Procedure
-
-First of all make sur that you have npm and yarn installed on your system.
-
-The first to do is to create a new react typescript project
-
-#### Setup dependencies
-
-Create an empty folder and run after these commands from the newly created folder :
-
-`yarn add @apollo/client graphql`
-
-`yarn add -D @graphql-codegen/cli`
-
-It will setup all the dependencies needed to generated the types and hooks.
+This guide is made to generate types and hooks (query/mutate) for the frontend based on the GraphQL API. This tool is used to avoid to do it manually.
 
 #### Declare GrahpQL queries
 
-To generate the types and hooks, you need to provide the queries that you'll be using, so you need to put a file named `queries.ts`, an example is provided :
+To generate new types and hooks, you need to update the file `queries.ts`. In this file you should describe the query you want to make, the types needed will be automatically deducted from your description.
 
-```ts
-import { gql } from '@apollo/client';
+#### Update queries and types
 
-export const QUERY_DOMAINS = gql`
-  query listDomains {
-    domains {
-      id
-    }
-  }
-`;
+To update or create new types and operations, you can run the following command :
 
-export const QUERY2 = gql`
-  query listVariables {
-    domains {
-      variables {
-        id
-      }
-    }
-  }
-`;
-
-...
+```bash
+yarn codegen
 ```
 
-#### Init codegen configuration
-
-To init codegen configuration, you can enter the following command
-
-`npx graphql-codegen init`
-
-After that you will need to provide some information :
-
-* What type of application are you building ?
-  * Choose `Application built with React`
-* Where is your schema ?
-  * Give the url of your graphql's endpoint (default : http://127.0.0.1:8081/graphql)
-* Where are your operations and fragments ?
-  * `./queries.ts`
-* Pick plugins
-  * Let the default 3 plugins : TS, TS Operations, TS React Apollo
-* Where to write the output
-  * `src/generated/graphql.tsx` (default)
-* Do you want to generated an introspection file ?
-  * no
-* How to name the config file ?
-  * `codegen.yml`
-* What script in package.json should run the codegen
-  * `codegen`
-
-After this process you will need to run `yarn install` in order to install the new dependencies that have been added to the package.json.
-
-#### Generate and integrate
-
-Everything is now configured, you just need to run `yarn codegen` it will generated all you need in ./src/generated/graphql.tsx. You can copy the content of the generated replace the previous one if there is one or just create a new file under /src/generated/graphql.tsx
-
-If an error occurs telling you `Unable to find template plugin matching typescript-operations` you should try to run this command `npm i -D @graphql-codegen/typescript change-case` (see issue in the link section) and retry the previous command.
-
-**Update queries.ts**
-
-If you needed to regenerate the GrahpQL types and hooks you can keep your folder that is already setup and just change the content of the queries.ts, re-run `yarn codegen` and that's it.
+This command will generate all the operations and types for you. Remeber you should place the graphql's operations in the file `queries.ts` under the folder `src/components/API/GraphQL`. Types will be all generated in one file under the name `types.generated.ts`, operations will be in `queries.generated.tsx` file finally all fragments under the file `fragments.generated.tsx`.
 
 ### Links
 

docs/get-started/Introduction.md

@@ -6,7 +6,7 @@ description: Introduction for developers
 
 The MIP is mainly composed by 3 components
 
-![](../.gitbook/assets/components.drawio.png)
+![](<../.gitbook/assets/components.drawio (1).png>)
 
 * **Frontend** : user interface (React.js)
 * **Gateway** : middleware used to abstract calls from an engine (Nest.js and GraphQL)
@@ -34,7 +34,7 @@ GraphQL is used to provide some useful features :
 
 ### Connectors
 
-In order to be able to communicate with an engine, the gateway need connectors. A connector is a concrete implementation of the interface `IEngineService`.
+In order to be able to communicate with an engine, the gateway need a connector. A connector is a concrete implementation of the interface `IEngineService`.
 
 ```typescript
 export default class DatashieldService implements IEngineService {
@@ -51,7 +51,7 @@ The code above is an example of a connector.
 
 ### Visualizations
 
-![](../.gitbook/assets/visualizations.png)
+![](<../.gitbook/assets/visualizations (1).png>)
 
 With the Frontend we will introduce a new way to deal with visualizations. Previously the visualizations were completely manage by the engine. As a part of abstraction from a specific engine we want to be able to delegate this task to the visualization components.
 

docs/get-started/Setup-development-environment.md

@@ -13,6 +13,7 @@ As we have seen in the previous chapter we need three component in order to setu
 * Engine
 * Frontend
 * Gateway
+  * DB (postgres)
 
 In this guide we will see how to setup the last two elements.
 
@@ -23,12 +24,13 @@ Make sure to have
 * [Node.js](https://nodejs.org)
 * [NPM](https://npmjs.com)
 * [Yarn](https://yarnpkg.com)
+* [Docker](https://docs.docker.com/get-docker/) and [docker-compose](https://docs.docker.com/compose/install/)
 
 installed in your computer.
 
 ## Setup Gateway
 
-First of all you should clone the repository 'gateway' either from the [Gitlab](https://gitlab.com/sibmip/gateway) or from the [GitHub](https://github.com/HBPMedical/gateway).
+First of all you should clone the repository either from the [Gitlab](https://gitlab.com/sibmip/gateway) or from the [GitHub](https://github.com/HBPMedical/gateway).
 
 Once the pull is completed, you can make the following commands
 
@@ -40,39 +42,31 @@ git checkout develop
 npm install
 ```
 
-After these steps you should be able to start the gateway in dev mode with the following command
+#### Run the DB
 
-```bash
-npm run start:dev
-```
+The gateway need a DB in order to work. [TypeORM](https://typeorm.io) is used to make the DB calls agnostic from the real implementation. 
 
-### env.defaults
+We provide a docker-compose to run a `postgres` DB, you can use it by running the following command
 
-There is an environment file that allows some configuration for the gateway.
-
-```yaml
-ENGINE_TYPE=local
-ENGINE_BASE_URL=http://127.0.0.1:8080/services/
-GATEWAY_PORT=8081
+```bash
+docker-compose up -d 
 ```
 
-* ENGINE\_TYPE
-  * Allows you to choose which connector you want to load, `local` is used for development purpose and is not intended to be used in production.
-* ENGINE\_BASE\_URL
-  * Indicate the endpoint for the engine, this parameter can be retrieve in the connector side. If you are using `local` connector this parameter is not useful.
-* GATEWAY\_PORT
-  * Indicate the port for the Gateway.
+For debugging purpose, you can omit the -d (detached) parameter.
+
+#### Run the Gateway
 
-These parameters can be overwrite by either :
+After the other steps have been completed, you should be able to start the gateway in dev mode with the following command
 
-* setting a variable in `.env` file (you can create it if it does not exist) along with the file .env.defaults in the root folder
-* or setting an environment variable on your system
+```bash
+npm run start:dev
+```
 
 ### GraphQL Playground
 
 Once you have started the Gateway, you can play with the GraphQL playground that is automatically integrated within the gateway, follow this link : [http://127.0.0.1:8081/graphql](http://127.0.0.1:8081/graphql). You should be able to see something like this :
 
-![GraphQL Playground](../.gitbook/assets/image.png)
+![GraphQL Playground](<../.gitbook/assets/image (1).png>)
 
 This environment is a tool provided by GraphQL to play with queries, mutations, etc...
 

for-developers/authentication.md

+# Authentication
+
+The authentication implementation is based on [passport.js](https://www.passportjs.org) it allows a flexible way to implement different strategies inside the gateway. 
+
+For now the authentication system is quite simple and only use JWT. The real implementation of  authorization and authentication is left to the connector. 
+
+#### How it works ?
+
+The communication between the frontend and the gateway is handled by JWT token who contains user information such as his username.
+
+![](<../.gitbook/assets/image (2).png>)
+
+The gateway will handle the authentication process with the frontend in a unique fashion always using a JWT token. This token can contains information specific to some connector. For that purpose the user model contains a field `extraFields` which basically a dictionary.&#x20;
+
+{% code title="user.model.ts" %}
+```typescript
+import { Field, ObjectType } from '@nestjs/graphql';
+import { Entity, PrimaryColumn, Column } from 'typeorm';
+
+@Entity({ name: 'user' })
+@ObjectType()
+export class User {
+  @PrimaryColumn()
+  @Field()
+  id: string;
+
+  @Field()
+  username: string;
+
+  @Field({ nullable: true })
+  fullname?: string;
+
+  @Field({ nullable: true })
+  email?: string;
+
+  @Column({ nullable: true, default: false })
+  @Field({ nullable: true })
+  agreeNDA?: boolean;
+
+  extraFields?: Record<string, any>;
+}
+```
+{% endcode %}
+
+This field can be used by the connector to store information related to the user as other token for engine API endpoints.
+
+#### Login&#x20;
+
+The real login system is delegated to the connector by using the `login` method in the interface.
+
+{% code title="engine.interface.ts" %}
+```typescript
+export interface IEngineService {
+  // ...
+  
+  /**
+   * Method that login a user with username and password
+   * @param username
+   * @param password
+   * @returns User object or empty if user not found
+   */
+  login?(
+    username: string,
+    password: string,
+  ): Promise<User | undefined>;
+
+  // ...
+}
+```
+{% endcode %}
+
+This method can be optional as the authentication can be made by a 3rd party system under the same domain as this is the case for `exareme`.
+
+When the login is performed, this function should return a `User` object and can feed the `extraFields` attribute with data needed to perform future request to the engine.
+
+#### Logout
+
+The same mechanism is applied to the logout system using the method logout from the engine.
+
+{% code title="engine.interface.ts" %}
+```typescript
+export interface IEngineService {
+  // ...
+  
+  logout?(req: Request
+  ): Promise<void>;
+
+  // ...
+}
+```
+{% endcode %}
+

for-developers/configuration/README.md

+# Configuration
+

for-developers/configuration/gateway.md

+---
+description: >-
+  This page description all the possible configuration that can be made in the
+  Gateway.
+---
+
+# Gateway
+
+### :toolbox: Options
+
+#### General
+
+| name               | type    | default                         | description                                                                                 |
+| ------------------ | ------- | ------------------------------- | ------------------------------------------------------------------------------------------- |
+| ENGINE\_TYPE       | string  | exareme                         | Define the connector that should be used : **`exareme, datashield, csv, local`**.           |
+| ENGINE\_BASE\_URL  | string  | http://127.0.0.1:8080/services/ | Specify the endpoint for the data source. The parameter will be provided for the connector. |
+| TOS\_SKIP          | boolean | false                           | Allow to skip the `terms of services` (this parameter is provided to the frontend)          |
+| GATEWAY\_PORT      | number  | 8081                            | Indicate the port that should be used by the gateway                                        |
+| NODE\_ENV          | string  | dev                             | Value can be `prod` or `dev`                                                                |
+| BASE\_URL\_CONTEXT | string  | null                            | Define context of the gateway. E.g. `api` if the api is under `http://127.0.0.1/api/`       |
+
+#### Authentication
+
+| name                          | type    | default  | description                                                                                                                                       |
+| ----------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| AUTH\_SKIP                    | boolean | false    | Allow to skip authentication. Warn: all routes will be accessible without authentication.                                                         |
+| AUTH\_JWT\_SECRET             | string  | N/A      | Secret that should be used to generate JWT token                                                                                                  |
+| AUTH\_JWT\_TOKEN\_EXPIRES\_IN | string  | '2d'     | <p>JWT token time to live.</p><p>Expressed in seconds or a string describing a time span <a href="https://github.com/vercel/ms">vercel/ms</a></p> |
+| AUTH\_COOKIE\_SAME\_SITE      | string  | 'strict' | Specify the cookie same site option. Value can be  `lax`, `strict` or `none`                                                                      |
+| AUTH\_COOKIE\_SECURE          | boolean | true     | Specify the cookie secure option. Should be set to true if same site is not set to `strict`.                                                      |
+
+#### Database
+
+| name         | type   | default   | description                     |
+| ------------ | ------ | --------- | ------------------------------- |
+| DB\_HOST     | string | localhost | Hostname                        |
+| DB\_PORT     | number | 5432      | Port number                     |
+| DB\_USERNAME | string | postgres  | Username                        |
+| DB\_PASSWORD | string | pass123   | Password                        |
+| DB\_NAME     | string | postgres  | Name of the database's instance |
+
+### Overwrite
+
+These parameters can be overwrite by either
+
+* setting a variable in `.env` file (you can create it if it does not exist) along with the file .env.defaults in the root folder
+* or setting an environment variable on your system
+
+Default variables are stored in the `.env.defaults` file and under the `db.config.ts` file for the database configuration.

for-developers/frontend/visualisations.md

+# Visualisations
+
+To see the different possible visualisations in the frontend we have integrated [storybook.js](https://storybook.js.org) directly in the frontend.
+
+Start the storybook by launching this command in the frontend folder
+
+```bash
+yarn storybook
+```
+
+This command will give you access to the a website with all the visualisation that are currently implemented.
+
+![Example of the storybook](<../../.gitbook/assets/image (3).png>)
+