aissous-amin/welcome-service-api

Nodejs Hexagonal Starter Kit

A starter kit to master your API development

First of all I highly recommend you to read the attached documentation to better master the hexagonal architecture

1. Introduction to clean architecture
2. Hexagonal Architecture
3. Bonus : A Git Workflow

Getting Started

TODO

• Add user roles and permission
• Add SonarQube
• Add CheckMarx
• Add test (Mocha, SuperTest, Sinon)

Advanced Topics

• Helmet
  • Helmet can help protect your app from some well-known web vulnerabilities by setting HTTP headers appropriately.
• Snyk
  • Ensure your dependencies are secure with Snyk
• Winston and Morgan
  • Do logging correctly with Morgan and Winston for a full log system (rotating-file-stream)
• Handle exceptions properly
  • Error Handling in Node.js
• Use env variable correctly
  • Use dotenv to set up your var environment
  • Use the env folder under the Conf layer to set up your env var per environnement
• Health Checks and Graceful Shutdown
  • You can find the Graceful Shutdown configuration in the infrastructure layer at ExpressServer.js (static close())
• Husky
  • We use Husky to improves your commits
    • Git-precommit-checks
    • Validate-branch-name
    • Conventional Commit
    • Commitlint & Commitizen
• HATEOAS and dynamic discovery of your API
  • We have implemented the hateoas structure of RFC 5988 format, you can modify the system to meet your own objectives (Search for creat_hateoas_structure under functionality file)
• Dealing with Problem Details for HTTP APIs rfc7807.
  • We implemented a ExpressResponseController mechanism in order to deal with Details Response standard problem and REST API Error Handling

  • You can improve this middleware with other HttpStatusCode according to your need!

• MSAL with passport-azure-ad and passport for Authentication
• Pagination system
  • A pagination mechanism is already in place for collection resource (Limit, Offset, Sort and Order)

Requirements

1. Docker-Compose

   • Once docker-compose is installed you can launch the project with the following command : docker-compose up -d
   • Lists all containers that are up and running with the following command : docker-compose ps

2. Node.js (LTS version)

3. mongodb

Other tools to be used if you want in your project:

• Load test: jMeter or Artillery.

Installation

• First you need to set up the following env variables :

You have to create an .env file inside the env file with the following elements

NODE_ENV=development
APP_SERVER_PORT=3001
APP_SERVER_HOST=localhost
APP_PREFIX=/api
DATABASE_SERVER=mongodb://localhost:27017/messages
LOG_ERROR_FILE=error.log
LOG_ACCESS_FILE=access.log
DEFAULT_LOG_DIR=C:\Users\J1056682\MyWorkSpace\log
SKIP_LOGGER=false
tenantID= your tenentID
clientID= your clientID
KEY= /Config/lib/localhost-private-key.pem //replace with your certKey
CERT= /Config/lib/localhost-cert.pem //replace witth your CERT

Run the project locally

    - `git clone [email protected]:TotalEnergies/nodejs-hexagonal-starter-kit.git`
    - `npm install`
    - `npm run prepare`
    - `npm run start`

Note : Generate a self signe certificate with openSSL : For demonstration purposes we used openssl to generate our self-signed certificate (not recommended for a production environment, you should use a Certificate Authority) To generate a self-signed certificate, run the following in your shell : openssl req -x509 -newkey rsa:4096 -nodes -sha256 -subj '//CN=localhost' -keyout localhost-private-key.pem -out localhost-cert.pem

• Generation of JsDoc documentation:

  • npm run doc

• Get help to format your commit message with Commitizen :

  • npx cz

You find the openapi specification here: swagger`

Note : the certificate and the private key are available in the /Config/lib directory you can ping the service with this command : - curl https://localhost:3001/api/messages

Hexagonal Architecture Layers

The different layers of the architecture

Application layer

• Orchestrate the domain objects to perform the tasks required by the end users.

Domain layer

• Includes all business logic, entities, events and any other type of object that contains business logic.

Infrastructure layer

• Technical features that support the previous layers, such as the network layer for example.

Persistence layer

• Allows to manage the Persistence aspect of the service.

DataBanding

• Communication between layers can only be done in a top-down manner, which means that a layer can never communicate directly with a layer located higher than it.