diff --git a/docs/components/core/legacy-auth.md b/docs/components/core/legacy-auth.md
new file mode 100644
index 0000000000000000000000000000000000000000..b641de002aa9a463d873b2aa541cac0db0536897
--- /dev/null
+++ b/docs/components/core/legacy-auth.md
@@ -0,0 +1 @@
+# Legacy AUTH
diff --git a/docs/components/middlewares/legacy-auth-middleware.md b/docs/components/middlewares/legacy-auth-middleware.md
new file mode 100644
index 0000000000000000000000000000000000000000..41e6048b601477f9bc872ddef2eca4512580da5b
--- /dev/null
+++ b/docs/components/middlewares/legacy-auth-middleware.md
@@ -0,0 +1,12 @@
+
+# Legacy Authentication Middleware
+
+## Features
+
+## Dependencies
+
+## Endpoints
+
+## Implementation
+
+The service is implemented using the [NestJS](https://nestjs.com/) framework. We refer the reader to the [NestJS-based micro-services](../../miscellaneous/nestjs-micro-services.md) page for further details concerning the latter framework and the features it provides.
diff --git a/docs/components/off-the-shelf-apps/api-gateway.md b/docs/components/off-the-shelf-apps/api-gateway.md
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..cb6977bf32376ba469a5dfcf308acd4b818c96be 100644
--- a/docs/components/off-the-shelf-apps/api-gateway.md
+++ b/docs/components/off-the-shelf-apps/api-gateway.md
@@ -0,0 +1,6 @@
+# API Gateway
+
+### TODO
+
+* Explain the reasons why Kong was chosen
+* Explain which features are used, in particular the AUTHN layer
diff --git a/docs/components/services/authentication.md b/docs/components/services/authentication.md
index 3dc331505c1586df2942981241657e6ec6459991..0c17ed4733c30336840b4fdbd217144cd3625a83 100644
--- a/docs/components/services/authentication.md
+++ b/docs/components/services/authentication.md
@@ -1,46 +1,55 @@
-
 # Authentication service
 
-## What it does
-
-This service provides two endpoints relative to the authentication of a user:
+## Features
 
-* A login endpoint that will allow a user to authenticate itself using its credentials (a username and an encrypted password). When the credentials are correct it will generate a JSON Web Token and set it as a cookie for the domain name specified in the configuration of the service. An xsrf token will also be returned in the response. Both the cookie and the xsrf token will be needed to make authenticated calls later.
+This service allows users to login to / logout from the Web Portal. Establishing an authenticated session is a prerequisite for managing user rights to restricted-access resources.
 
-* A logout endpoint, which signs out the user by deprecating the cookie set with the login endpoint.
+## Dependencies
 
-This service also provides endpoints to retrieve and update a user profile.
+The service relies on
 
-## How it works
+* the [API Gateway](../off-the-shelf-apps/api-gateway.md), in particular its Admin API;
+* external identity providers, which actually store user profiles and can verify user credentials. Despite being designed to potentially support different identity providers, in the present implementation only the [Legacy AUTH Identity Provider](../core/legacy-auth.md) is supported. A [middleware](../middlewares/legacy-auth-middleware.md) was developed, so as to facilitate the interaction between this service and the Legacy AUTH Identity Provider.
 
 ![authentication-service](../../assets/authentication-service.png)
 
-The entrypoint of the service is a REST API provided by a [NestJS](https://github.com/nestjs/nest) application. It depends on two other services:
 
-* The Legacy Authentication Middleware to verify the identity of the user and retrieve its profile (called through our api gateway: Kong)
-* The Admin API of Kong to get the user specific secrets in order to sign the JSON Web Tokens
+## Endpoints
+
+This service provides five **endpoints**:
+
+1. A **login** endpoint per identity provider (just one in the present implementation, namely `/login/legacy`), allowing users to authenticate using a username/password pair. In case the identity provider confirms that user credentials are correct, a couple of cookies are set:
+    1. an HTTP-only cookie including an **access token**, including in turn a JSON Web Token (JWT), signed by the API Gateway, namely Kong.
+    2. a cookie including an **XSRF token** (generated as a version 4 UUID).
+
 
-## API documentation
+    Both the access token and the XSRF token are needed to issue authenticated requests. We refer the reader to a [dedicated page](../../miscellaneous/security.md) for further information about security.
 
-NestJS provides a [swagger module](https://docs.nestjs.com/recipes/swagger) that can be easily integrated. Using specific annotations alongside your endpoints declaration, this module will automatically generates a swagger documentation, reachable at `/api-doc`.
+2. A **logout** endpoint, `/logout`, which signs out the user by deprecating the cookie set by the login endpoint.
 
-## Service health
+3. An **user info** endpoint, allowing one to fetch an user profile.
 
-NestJS provides a [health module](https://github.com/nestjs/terminus) based on Terminus, that gives you the opportunity to declare predefined or custom health indicators. It exposes the health status of the service at `/health`.  
-This service will return a `200` http status code when all indicators are healthy. Otherwise it will return a `503` http status code. 
+4. An **user info update** endpoint, `/user/update` allowing one to update an user profile.
 
-For this service we declared two health indicators that verify that: 
-* the Kong API gateway is up
-* the legacy authentication middleware is up
+5. An **health** endpoint, `/health`, returning a `200` HTTP Status Code in case the service is healthy, `503` in the opposite case. For this service to be healthy, two conditions must be fulfilled:
+    * the [API Gateway](../off-the-shelf-apps/api-gateway.md) must be up;
+    * the [Legacy AUTH Middleware](../middlewares/legacy-auth-middleware.md) must be up.
 
-## Stats
 
-We are using a Node module called [swagger-stats](http://swaggerstats.io/).  
-It traces API calls, monitors API performance and usage statistics. It exposes the metrics in different formats, such as Prometheus format, so you may use Prometheus and Graphana for API monitoring and alerting.  
-Those metrics are available at `/swagger-stats/metrics`.
+## Implementation
 
-For more information about this module, visit the [official swagger-stat page](http://swaggerstats.io/docs.html).
+The service is implemented using the [NestJS](https://nestjs.com/) framework. We refer the reader to the [NestJS-based micro-services](../../miscellaneous/nestjs-micro-services.md) page for further details concerning the latter framework and the features it provides.
 
-## Docker
-It is possible to run this service using Docker containers, using the `docker-compose.yml` and `Dockerfile` files.  
-For more information, refer to the project [authentication-service][add a link]
\ No newline at end of file
+### TO FURTHER DEVELOP
+
+* What's the interplay between this service and Kong? Let's provide sequence diagrams!
+* How is the access token generated and signed?
+* What is the difference between the cookie expiration time and that of the JWT for the Legacy Middleware?
+
+
+<!-- ## How it works
+
+The entrypoint of the service is a REST API provided by a [NestJS](https://github.com/nestjs/nest) application. It depends on two other services:
+
+* The Legacy Authentication Middleware to verify the identity of the user and retrieve its profile (called through our api gateway: Kong)
+* The Admin API of Kong to get the user specific secrets in order to sign the JSON Web Tokens -->
diff --git a/docs/components/services/legacy-auth-middleware.md b/docs/components/services/legacy-auth-middleware.md
deleted file mode 100644
index a4d7c1d44bedf9d8ca2519894a70774fbe2724c3..0000000000000000000000000000000000000000
--- a/docs/components/services/legacy-auth-middleware.md
+++ /dev/null
@@ -1,42 +0,0 @@
-
-# Legacy Authentication middleware
-
-## What it does
-
-
-
-## How it works
-
-<!-- ![legacy-auth-middleware-service](../../assets/legacy-auth-middleware-service.png) -->
-
-The entrypoint of the service is a REST API provided by a [NestJS](https://github.com/nestjs/nest) application. 
-
-<!-- It depends on two other services:
-
-* The Legacy Authentication Middleware to verify the identity of the user and retrieve its profile (called through our api gateway: Kong)
-* The Admin API of Kong to get the user specific secrets in order to sign the JSON Web Tokens -->
-
-## API documentation
-
-NestJS provides a [swagger module](https://docs.nestjs.com/recipes/swagger) that can be easily integrated. Using specific annotations alongside your endpoints declaration, this module will automatically generates a swagger documentation, reachable at `/api-doc`.
-
-## Service health
-
-NestJS provides a [health module](https://github.com/nestjs/terminus) based on Terminus, that gives you the opportunity to declare predefined or custom health indicators. It exposes the health status of the service at `/health`.  
-This service will return a `200` http status code when all indicators are healthy. Otherwise it will return a `503` http status code. 
-
-<!-- For this service we declared two health indicators that verify that: 
-* the Kong API gateway is up
-* the legacy authentication middleware is up -->
-
-## Stats
-
-We are using a Node module called [swagger-stats](http://swaggerstats.io/).  
-It traces API calls, monitors API performance and usage statistics. It exposes the metrics in different formats, such as Prometheus format, so you may use Prometheus and Graphana for API monitoring and alerting.  
-Those metrics are available at `/swagger-stats/metrics`.
-
-For more information about this module, visit the [official swagger-stat page](http://swaggerstats.io/docs.html).
-
-## Docker
-It is possible to run this service using Docker containers, using the `docker-compose.yml` and `Dockerfile` files.  
-For more information, refer to the project [legacy-auth-middleware][add a link]
\ No newline at end of file
diff --git a/docs/components/specific-apps/admin-gui.md b/docs/components/specific-apps/admin-gui.md
index 2edf8f70dec89be7de41faf358884d9cd0c61423..7cd08929a95107e96497befe6460f93c5b295a69 100644
--- a/docs/components/specific-apps/admin-gui.md
+++ b/docs/components/specific-apps/admin-gui.md
@@ -4,7 +4,7 @@
 
 The Admin GUI is a web user interface dedicated to admin users.
 
-It let them administrate the database of different services such as resources (resources, formats, projections), partners, reuse... 
+It let them administrate the database of different services such as resources (resources, formats, projections), partners, reuse...
 
 It also has a section that provides logs of the datasets indexation jobs. It can be usefull to track indexation errors, execution time for each task...
 
@@ -22,7 +22,7 @@ npm install -g @angular/cli
 
 Open the `/src/assets/config/config.json` file and update the configuration in order to match yours.
 
-For more explainations on how the configuration system works refer to the dedicated [section](../miscellaneous/multi-environments-docker-build-for-angular.md).
+For more explainations on how the configuration system works refer to the dedicated [section](../../miscellaneous/multi-environments-docker-build-for-angular.md).
 
 
 
@@ -80,4 +80,4 @@ docker-compose --project-name admin-gui up
 
 ## Authentication
 
-It uses the same authentication methods as the portail data web app, so if you have an account you will be able to log in. However only a user belongging to the admin group will be able to create, modify and delete entities. The groups are managed by the api gateway, for more information refer to the [Authentication and Authorization](../miscellaneous/authentication&authorization.md) section.
\ No newline at end of file
+It uses the same authentication methods as the portail data web app, so if you have an account you will be able to log in. However only a user belongging to the admin group will be able to create, modify and delete entities. The groups are managed by the api gateway, for more information refer to the [Authentication and Authorization](../../miscellaneous/authentication&authorization.md) section.
diff --git a/docs/components/specific-apps/web-app.md b/docs/components/specific-apps/web-app.md
index 8f31fb34bb6a466b4d8a187b59fae25323e4deb5..66c760037c05b7b80d19ec231391ee98295037fd 100644
--- a/docs/components/specific-apps/web-app.md
+++ b/docs/components/specific-apps/web-app.md
@@ -5,7 +5,7 @@ Organize a folders and files structure inside a project is never an easy task, a
 We think that at the beginning we should just not overthink about it, choose one way to do it, keep to it, until a natural re-organization will happen if needed.   
 Here is our `/src` folder structure:
 
-![folers structure](../assets/folders.png)
+![folers structure](../../assets/folders.png)
 
 * `src/app`: where the Angular code is located. With time we organized this part in different modules taking care on one main functionnality each. Inside one module each component has its own folder with one `.ts`, one `.scss` and one `html` file.   
 * `/src/assets`: contains all the images, favicon, svg, fonts, Mapbox style files.
@@ -52,4 +52,4 @@ So we used...Elasticsearch. It is super fast and even have geographical research
 
 ## Credits
 
-## Licence
\ No newline at end of file
+## Licence
diff --git a/docs/index.md b/docs/index.md
index 7a8e1d80a3ffaeae248f22f16a118ef97117c9dc..aa3c4b9bc764d898e6f1670821eabad7b7284ef4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,2 +1 @@
-# Welcome to the functional documentation of portail-data
-
+# Welcome!
diff --git a/docs/accessibility/accessibility.md b/docs/miscellaneous/accessibility.md
similarity index 97%
rename from docs/accessibility/accessibility.md
rename to docs/miscellaneous/accessibility.md
index 3f7da67c5cb280df7ccf56fe2329f3f0bacf6f02..4cea8e15dbd04e4152f23bb02a25d6a5e35f2826 100644
--- a/docs/accessibility/accessibility.md
+++ b/docs/miscellaneous/accessibility.md
@@ -25,7 +25,7 @@ npm install -g pa11y-ci
 Then create a **.pa11y1** json file.
 ```
 {
-  "urls": [ 
+  "urls": [
     "https://data.beta.grandlyon.com/fr/accueil"
   ]
 }
@@ -38,4 +38,4 @@ pay11-ci
 It is also possible to save the report as a json file:
 ```
 pay11-ci --json > report.json
-```
\ No newline at end of file
+```
diff --git a/docs/miscellaneous/nestjs-micro-services.md b/docs/miscellaneous/nestjs-micro-services.md
new file mode 100644
index 0000000000000000000000000000000000000000..34964ee3fbb2b52a33d053805d2cf45786027999
--- /dev/null
+++ b/docs/miscellaneous/nestjs-micro-services.md
@@ -0,0 +1,13 @@
+# NestJS-based micro-services
+
+## An overview of NestJS
+
+...
+
+## API documentation
+
+NestJS provides a [swagger module](https://docs.nestjs.com/recipes/swagger) that can be easily integrated. By using dedicated annotations alongside the various endpoint declarations, the developer can provide the module information to automatically generate a swagger documentation, reachable at `/api-doc`.
+
+## Health checks
+
+NestJS provides a health module based on [Terminus](https://github.com/nestjs/terminus), allowing developers to declare predefined and/or custom health indicators. By default, the health status of a given NestJS service is available through the `/health` endpoint.
diff --git a/docs/miscellaneous/security.md b/docs/miscellaneous/security.md
new file mode 100644
index 0000000000000000000000000000000000000000..271354b559dbda06748d653ab14960c2161a4886
--- /dev/null
+++ b/docs/miscellaneous/security.md
@@ -0,0 +1,6 @@
+# Security
+
+## XSRF Token
+
+
+## User password encryption
diff --git a/docs/overview/index.md b/docs/overview/index.md
index 4e65c33788752fe0191bc616f1bda40c59f4b33b..5897af822a59f840a53950665ec22a70d51927cd 100644
--- a/docs/overview/index.md
+++ b/docs/overview/index.md
@@ -14,7 +14,7 @@ package "data.grandlyon.com" {
 @enduml
 ```
 
-In this respect, the Web Portal is just one of the various Core's clients, in the same way as 3rd-party client applications:
+In this respect, the Web Portal is just one among the (hopefully) many Core's clients, in the same way as 3rd-party client applications:
 
 ```plantuml
 @startuml
@@ -106,7 +106,7 @@ A6 | Postfix | [Link](http://www.postfix.org/) | SMTP Server
 
 ID | Name | Repo | Doc | Usage | Deps
 --- | --- | --- | --- | --- | ---
-M1 | Legacy AUTH | ... | ... | Facilitating the interaction between the Web Portal Authentication Service (S1) and the AUTHN/AUTHZ Service (C1) hosted by data.grandlyon.com's Core macro-component |  C1
+M1 | Legacy AUTH | ... | ... | Facilitating the interaction between the Web Portal Authentication Service (S1) and the AUTHN/AUTHZ Service (C1) hosted by data.grandlyon.com's Core macro-component |  C1, S5
 
 ### Proxies
 
@@ -125,6 +125,13 @@ ID | Name | Repo | Doc | Usage | Deps
 I1 | Editorial Content | ... | ... | Indexing the posts and pages edited in Ghost | A2
 I2 | Metadata and Data | ... | ... | Indexing the metadata and data hosted, respectively, by data.grandlyon.com's catalog (C3) and database (C4) | C3, C4
 
+### Tools
+
+ID | Name | Repo | Doc | Usage | Deps
+--- | --- | --- | --- | --- | ---
+T1 | MinIO master-slave replication tool | ... | ... | Replicating/mirroring the assets stored in one "master" instance of MinIO to some other "slave" instances | A5
+
+
 
 ### Services
 
@@ -132,11 +139,11 @@ In alphabetical order:
 
 ID | Name | Repo | Doc | Usage | Deps
 --- | --- | --- | --- | --- | ---
-S1 | Authentication | ...  | ... | Allowing users to create accounts and to perform logins and logouts | M1, S5
+S1 | Authentication | ...  | [Link](../components/services/authentication.md) | Allowing users to create accounts and to perform logins and logouts | A3, S5
 S2 | Changelog | [Link](https://gitlab.alpha.grandlyon.com/refonte-data/service-changelog)  | ... | Keeping track of the new features available to users throughout the developments|
 S3 | Credits | ... | ... | Catalog of the Open Source initiatives powering the data.grandlyon.com project | S6 |
 S4 | CSV Catalog Downloader | ... | ... |  Allowing users to download cached CSV exports of the metadata catalog | C3 |
-S5 | Mail | ... | [Link](../features/services/mail.md) | Sending e-mails to both end- and back-office users | A6
+S5 | Mail | ... | [Link](../components/services/mail.md) | Sending e-mails to both end- and back-office users | A6
 S6 | Media Library | ... | ... | Managing the images shown across the various pages of the Web Portal (organizations, posts, ...) |
 S7 | Organizations | ... | ... | A catalog of the partners of the data.grandlyon.com, typically Data Providers | S6
 S8 | Resources Helper | ... | ... | Assisting users in the composition of custom queries against the Core APIs |
diff --git a/mkdocs.yml b/mkdocs.yml
index 005d6c2b7083cc20575af0d0748c4847af76d698..91a5d34981356d9b2a5be712ef5d673ed2204142 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -22,33 +22,44 @@ markdown_extensions:
         server: http://www.plantuml.com/plantuml
 
 nav:
+    - Home: index.md
     - Overview: overview/index.md
     - Features: features/index.md
     - Architecture: architecture/index.md
     - Components:
       - Core Components:
-        - Off-the-shelf applications:
-          - API Gateway: components/off-the-shelf-apps/api-gateway.md
-          - Headless CMS: components/off-the-shelf-apps/cms.md
-          - Search Engine: components/off-the-shelf-apps/elasticsearch.md
-        # - Middlewares:
+        - Legacy AUTH: components/core/legacy-auth.md
+      - Off-the-shelf applications:
+        - API Gateway: components/off-the-shelf-apps/api-gateway.md
+        - Headless CMS: components/off-the-shelf-apps/cms.md
+        - Search Engine: components/off-the-shelf-apps/elasticsearch.md
+      - Middlewares:
+        - Legacy AUTH: components/middlewares/legacy-auth-middleware.md
         # - Proxies:
       - Indexers:
         - Metadata and Data: components/indexers/metadata-and-data.md
         - Editorial Content: components/indexers/editorial-content.md
       - Services:
         - Authentication: components/services/authentication.md
+        - CSV Catalog Downloader: components/services/csv-catalog-downloader.md
+        - Mail: components/services/mail.md
+        - Media Library: components/services/media-library.md
         - Organizations: components/services/organizations.md
         - Resources: components/services/resources.md
       - Specific applications:
         - Web App: components/specific-apps/web-app.md
         - Admin GUI: components/specific-apps/admin-gui.md
     - Administration: administration/admin-tools.md
+    - Deployment:
+      - 2019 deployment of the first public beta version: deployment/beta-deployment.md
     - Monitoring: monitoring/monitoring.md
-    #- Authentication & Authorization: miscellaneous/authentication&authorization.md
     - Other:
+      - Security: miscellaneous/security.md
+      - NestJS-based micro-services: miscellaneous/nestjs-micro-services.md
+      - Accessibility: miscellaneous/accessibility.md
+      - AUTHN & AUTHZ: miscellaneous/authentication&authorization.md
       - Gitflow: miscellaneous/gitflow-ci-cd.md
       - VSCode: miscellaneous/vscode-settings.md
       - SASS recommendation: miscellaneous/sass-recommendation.md
       - Webapp-auth: miscellaneous/webapp-auth.md
-      - Multi-environment docker build for Angular app: miscellaneous/multi-environments-docker-build-for-angular
+      - Multi-environment docker build for Angular app: miscellaneous/multi-environments-docker-build-for-angular.md