diff --git a/docs/architecture/services/authentication.md b/docs/architecture/services/authentication.md index 1c80f37db372d4f9c6763fddc176f61f393c0bfc..3dc331505c1586df2942981241657e6ec6459991 100644 --- a/docs/architecture/services/authentication.md +++ b/docs/architecture/services/authentication.md @@ -22,21 +22,21 @@ The entrypoint of the service is a REST API provided by a [NestJS](https://githu ## API documentation -NestJS provides a swagger module that can be easily integrated. Using specific annotations alongside your endpoints declaration, this module will automatically generates a swagger documentation, reachable at `/api-docs`. +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 predifined or custom health indicators. It exposes the health status of the service at `/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: +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 alterting. +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). diff --git a/docs/architecture/services/mail.md b/docs/architecture/services/mail.md index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..f74485404ba624e4e2ac4a76cc578759b0ac67e0 100644 --- a/docs/architecture/services/mail.md +++ b/docs/architecture/services/mail.md @@ -0,0 +1,36 @@ +# Mail service + +## What it does + +This service allow to deliver mails to any email address from the address specified in the configuration. It also provides two particular endpoints, one for the user to give a feedback and another one for general contact purpose. Those endpoints will both send an email to the admin address specified in the configuration. + +## How it works + + + +The entrypoint of the service is a REST API provided by a [NestJS](https://github.com/nestjs/nest) application. The service builds email bodies based on the information it receives and on the provided HTML templates. It then format a JSON with all the properties (to, from, body...) expected by an SMTP server to correctly send an email. + +However the service does not send this JSON directly to the distant SMTP server. Indeed as a connection failure might occure, we chose to persist this object in a RabbitMQ queue. Then a small worker written in Node.js will consume the messages from the queue and send it to the SMTP server if correctly formatted. The messages will be removed (acknoledged) from the queue only if the SMTP received the message. + +## 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 an health indicator that verify that the connection to the RabbitMQ is available. + +## 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 [service-email][add a link] \ No newline at end of file diff --git a/docs/architecture/services/media-library.md b/docs/architecture/services/media-library.md index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..64a2e0d21e4828d73ebd28c0dcc8cffdd2d0ce7d 100644 --- a/docs/architecture/services/media-library.md +++ b/docs/architecture/services/media-library.md @@ -0,0 +1,40 @@ +# Media library service + +## What it does + +This service allows to upload a file in the configured bucket of a defined instance of [Minio](https://min.io/) (compatible with S3). + +## How it works + + + +The entrypoint of the service is a REST API provided by a [NestJS](https://github.com/nestjs/nest) application. The service uses the [Javascript MinIO SDK](https://docs.min.io/docs/javascript-client-quickstart-guide.html) to interact with a running instance of Minio. + +Before uploading the file, it makes sure that the specified bucket is created. If it is not the case, it creates it with a `public read access`. + +The files are classified in sub-buckets as following `/<specified-bucket-name>/<year-YYYY>/<month-MM>/`. + +The uploaded files keep there original name but are prefixed by an md5 computed based on their content with gives the following pattern for file names: `<md5>-<original-name>`. This means that if we upload twice the exact same picture, with the same name there will be only on file stored in MinIO. + +## 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 implemented a custom health indicator that checks the connection to MinIO giving the total number of buckets when the connection is succesful. + +## 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 [service-media-library][add a link] \ No newline at end of file diff --git a/docs/architecture/services/organizations.md b/docs/architecture/services/organizations.md index f04d41c4e3057f307cd29b2e89d20c9de770656e..0637a0931ba5aeec7ff31ca162fa82c1bdfb6f5c 100644 --- a/docs/architecture/services/organizations.md +++ b/docs/architecture/services/organizations.md @@ -1,7 +1,5 @@ # Organizations service - - ## What it does This service provides a list of organizations with different information about it (such as description, logo..etc). In our application, one organization is usually a provider of data, used in the Portal Open Data. It can be a public actor or a private one. @@ -15,11 +13,11 @@ The entrypoint of the service is a REST API provided by a [NestJS](https://githu ## API documentation -NestJS provides a swagger module that can be easily integrated. Using specific annotations alongside your endpoints declaration, this module will automatically generates a swagger documentation, reachable at `/api-doc`. +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 predifined or custom health indicators. It exposes the health status of the service at `/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 an health indicator that verifies that it can connect to the database. @@ -27,7 +25,7 @@ For this service we declared an health indicator that verifies that it can conne ## 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 alterting. +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). diff --git a/docs/architecture/services/resources.md b/docs/architecture/services/resources.md index 836f9f450ad32c1ea8321fff260041b4728849cf..2b65ea858fe30c5c43a12eae2d1084e65611456d 100644 --- a/docs/architecture/services/resources.md +++ b/docs/architecture/services/resources.md @@ -17,11 +17,11 @@ The entrypoint of the service is a REST API provided by a [NestJS](https://githu ## API documentation -NestJS provides a swagger module that can be easily integrated. Using specific annotations alongside your endpoints declaration, this module will automatically generates a swagger documentation, reachable at `/api-doc`. +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 predifined or custom health indicators. It exposes the health status of the service at `/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 an health indicator that verifies that it can connect to the database. @@ -29,7 +29,7 @@ For this service we declared an health indicator that verifies that it can conne ## 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 alterting. +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). diff --git a/docs/architecture/uml-test.md b/docs/architecture/uml-test.md deleted file mode 100644 index 3324a5b948ad5f41364720126f2aead1a4903fef..0000000000000000000000000000000000000000 --- a/docs/architecture/uml-test.md +++ /dev/null @@ -1,4 +0,0 @@ -```plantuml format="png" classes="uml myDiagram" alt="My super diagram placeholder" title="My super diagram" width="300px" height="300px" - Goofy -> MickeyMouse: calls - Goofy <-- MickeyMouse: responds -``` \ No newline at end of file diff --git a/docs/assets/mail-service.png b/docs/assets/mail-service.png new file mode 100644 index 0000000000000000000000000000000000000000..8729bfa95ca0ba053de7fc93efe1c81dae7db2db Binary files /dev/null and b/docs/assets/mail-service.png differ diff --git a/docs/assets/media-library-service.png b/docs/assets/media-library-service.png new file mode 100644 index 0000000000000000000000000000000000000000..b13811342853ec729e33b309c3349d09b7f8fae9 Binary files /dev/null and b/docs/assets/media-library-service.png differ