NESTJS-API-ARCHITECTURE

Documentation available in languages

Introduction

This project was developed for educational purposes to explore the NestJS framework. It serves as a practical study to "adapt*" concepts like Clean Architecture and Hexagonal Architecture, promoting good software design practices, with a clear separation of responsibilities and abstraction of external dependencies.

1. Installation Requirements

To run the project, you will need the following requirements:

• Operating System: Linux Ubuntu / Mint
• Docker: Ensure Docker is installed on your machine.
• Docker Compose: Install Docker Compose to orchestrate containers.
• Makefile: Ensure you have Makefile installed to simplify command execution.
• MongoDB: Version 8.x of MongoDB running in a Docker container.
• NodeJs: Version 22.x of NodeJs running in a Docker container.
• NodeJs: Version 20.x of NodeJs installed your machine.
• Yarn: Versão 1.22.x do Yarn installed your machine.

1.1. Project Structure

This project closely resembles Clean Architecture and Hexagonal Architecture as it promotes a clear separation of responsibilities and abstraction of external dependencies.
This approach enhances maintainability, scalability, and testability while allowing the application to evolve without directly impacting core business rules.

The division is organized into three main modules, each with a specific responsibility:

timesheet-in-transit-api/
│-- app/
│   │-- src/
│   │   │-- app.module.ts
│   │   │-- database.module.ts
│   │   │-- index.ts
│   │   │-- main.ts
│   │   │-- seed.module.ts
│   │   │-- seed.ts
│   │   │-- entrypoints/
│   │   │   │-- consumers/
│   │   │   │-- web/
│   │   │   │   │-- config/
│   │   │   │   │-- rest/
│   │   │   │   │-- shared/
│   │   │-- core/
│   │   │   │-- domain/
│   │   │   │   │-- entities/
│   │   │   │   │-- enums/
│   │   │   │   │-- exceptions/
│   │   │   │-- providers/
│   │   │   │   │-- config-env/
│   │   │   │   │-- integrations/
│   │   │   │   │-- queue/
│   │   │   │   │-- repositories/
│   │   │   │-- usecases/
│   │   │   │   │-- auth/
│   │   │   │   │-- notification/
│   │   │   │   │-- orders/
│   │   │-- infrastructure/
│   │   │   │-- config-env/
│   │   │   │-- integrations/
│   │   │   │-- queue/
│   │   │   │-- repositories/
│   │   │-- shared/
│   │   │   │-- audit/
│   │   │   │-- config/
│   │-- test/
│   │   │-- entrypoints/
│   │   │   │-- web/
│   │   │   │   │-- rest/

entrypoints

The entrypoints module is responsible for managing the application's entry points, such as web, jobs, and consumers.

Important: It must not contain business logic. This module may include input data validation for request objects.

core

The core module manages all the application's business logic. Key guidelines include:

• This module must be autonomous and free of external dependencies. Do not use external frameworks or libraries directly in core.
• The domain folder within the module contains the entities and granular business logic.
• Outgoing communication to external systems must be handled through interfaces defined in the providers module.
• Incoming communication must occur through interfaces in the usecases module.

infrastructure

The infrastructure module manages the application's external communication, such as:

• Database Connections
• API Integrations
• Messaging Systems

Important: The infrastructure module must not contain business logic.

shared

The shared module contains functionality and utilities that are shared between the entrypoints and infrastructure. It should be used to include functionality that does not involve business rules, such as validations input, common error handling, and other external integration utilities.

Important: The core layer must not use the shared module, as the business logic must remain independent of external functionalities.

2. Steps to Run the Project

2.1. Starting the Project in Development Mode

Follow the steps below to run the project in development mode.

2.1.1. Copy the configuration file:

• We recommend creating an alias dcli to execute the command: docker compose -f docker-compose.cli.yml run --rm

  chmod +x ./add_alias_cli.sh && ./add_alias_cli.sh

2.1.2. Installing aws cli:

• Install and configure aws cli:

  curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
  unzip awscliv2.zip
  sudo ./aws/install

• Configuring AWS region:

  nano ~/.aws/config

[default]
region = us-east-1
output = json

• Configuring AWS credentials (optional):

  nano ~/.aws/credentials

[default]
aws_access_key_id = <aws_access_key_id>
aws_secret_access_key =  <aws_secret_access_key>

2.1.3. Copy the configuration file:

• Copy the .env.dist file to .env using the command:

  cp .env.dist .env

2.2. Start the project with Docker using the commands:

• Creates the necessary Docker network:

  make create-network

• Builds Docker images:

  make build

• Installs project dependencies:

  make install

• Updates project dependencies:

  make upgrade-lib

• Seeds the database with initial data:

  make seed

• Starts the MongoDB container:

  make mongodb

• Starts the LocalStack container:

  make localstack-dev

• Creates queues in LocalStack:

  make create-queue-local

• Starts the application in development mode:

  make dev

• Runs lint and code formatting:

  make lint-format

• Automatically generates indices (if needed):

  make generate-index

• Automatically generates test file:

  make generate-test-file

• Runs test:

  make test

• Runs test with coverage:

  make test-coverage

• Run to add new dependency with yarn:

  dcli yarn add <your_dependency>

2.3. Documentation

The project includes several forms of documentation accessible locally:

• Swagger UI - Interactive Interface
• Swagger JSON - Swagger Document
• Health Check - Application Health Verification

2.3.1. Diagrams

For a better understanding of the application's flow, refer to the diagrams below:

• Diagram