{"id":24344200,"url":"https://github.com/hemicharly/nestjs-api-architecture","last_synced_at":"2026-04-11T17:04:06.976Z","repository":{"id":270018307,"uuid":"909147546","full_name":"hemicharly/nestjs-api-architecture","owner":"hemicharly","description":"This project was developed for educational purposes, aiming to explore and deepen knowledge of the NestJS framework. It serves as a practical study for the adaptation of concepts such as Clean Architecture and Hexagonal Architecture.","archived":false,"fork":false,"pushed_at":"2025-03-03T09:05:48.000Z","size":2544,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-03T10:23:36.122Z","etag":null,"topics":["clean-architecture","docker","express","hexagonal-architecture","localstack","mongodb","nestjs","nodejs","sqs","sqs-consumer","sqs-producer"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hemicharly.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-27T21:20:56.000Z","updated_at":"2025-01-06T21:48:24.000Z","dependencies_parsed_at":"2025-03-03T10:21:40.763Z","dependency_job_id":"84a76ec8-06a1-44d3-b184-f29e5e5620bf","html_url":"https://github.com/hemicharly/nestjs-api-architecture","commit_stats":null,"previous_names":["hemicharly/timesheet-in-transit-api","hemicharly/nestjs-api-architecture"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hemicharly%2Fnestjs-api-architecture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hemicharly%2Fnestjs-api-architecture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hemicharly%2Fnestjs-api-architecture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hemicharly%2Fnestjs-api-architecture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hemicharly","download_url":"https://codeload.github.com/hemicharly/nestjs-api-architecture/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243126642,"owners_count":20240459,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clean-architecture","docker","express","hexagonal-architecture","localstack","mongodb","nestjs","nodejs","sqs","sqs-consumer","sqs-producer"],"created_at":"2025-01-18T09:32:36.302Z","updated_at":"2026-04-11T17:04:06.970Z","avatar_url":"https://github.com/hemicharly.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NESTJS-API-ARCHITECTURE\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"http://nestjs.com/\" target=\"blank\"\u003e\u003cimg src=\"https://nestjs.com/img/logo-small.svg\" width=\"120\" alt=\"Nest Logo\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"app/test/badges/entrypoints.svg\" alt=\"Entrypoints\" style=\"margin: 2px\"\u003e\n  \u003cimg src=\"app/test/badges/core.svg\" alt=\"Core\" style=\"margin: 2px\"\u003e\n  \u003cimg src=\"app/test/badges/infrastructure.svg\" alt=\"Infrastructure\" style=\"margin: 2px\"\u003e\n  \u003cimg src=\"app/test/badges/shared.svg\" alt=\"Shared\" style=\"margin: 2px\"\u003e\n\u003c/p\u003e\n\n### Documentation available in languages\n\n[![en](https://img.shields.io/badge/lang-en-blue.svg)](README.md)\n[![pt-br](https://img.shields.io/badge/lang-pt--br-green.svg)](README.pt-br.md)\n\n## Introduction\n\nThis project was developed for educational purposes to explore the **NestJS** framework. It serves as a practical study\nto \"**adapt**\" concepts like **Clean Architecture** and **Hexagonal Architecture**, promoting **good software design\npractices**, with a clear separation of responsibilities and abstraction of external dependencies.\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"diagram/architecture-timesheet-in-transit-api.png\" alt=\"architecture-timesheet-in-transit-api\"\u003e\n\u003c/p\u003e\n\n## 1. Installation Requirements\n\nTo run the project, you will need the following requirements:\n\n* **Operating System**: Linux Ubuntu / Mint\n* **Docker**: Ensure Docker is installed on your machine.\n* **Docker Compose**: Install Docker Compose to orchestrate containers.\n* **Makefile**: Ensure you have Makefile installed to simplify command execution.\n* **MongoDB**: Version 8.x of MongoDB running in a Docker container.\n* **NodeJs**: Version 22.x of NodeJs running in a Docker container.\n* **NodeJs**: Version 20.x of NodeJs installed your machine.\n* **Yarn**: Versão 1.22.x do Yarn installed your machine.\n\n## 1.1. Project Structure\n\nThis project closely resembles **Clean Architecture** and **Hexagonal Architecture** as it promotes a clear separation\nof responsibilities and abstraction of external dependencies.  \nThis approach enhances maintainability, scalability, and testability while allowing the application to evolve without\ndirectly impacting core business rules.\n\nThe division is organized into three main modules, each with a specific responsibility:\n\n```lua\nNESTJS-API-ARCHITECTURE/\n│-- app/\n│   │-- src/\n│   │   │-- app.module.ts\n│   │   │-- database.module.ts\n│   │   │-- index.ts\n│   │   │-- main.ts\n│   │   │-- seed.module.ts\n│   │   │-- seed.ts\n│   │   │-- entrypoints/\n│   │   │   │-- consumers/\n│   │   │   │-- web/\n│   │   │   │   │-- config/\n│   │   │   │   │-- rest/\n│   │   │   │   │-- shared/\n│   │   │-- core/\n│   │   │   │-- domain/\n│   │   │   │   │-- entities/\n│   │   │   │   │-- enums/\n│   │   │   │   │-- exceptions/\n│   │   │   │-- providers/\n│   │   │   │   │-- config-env/\n│   │   │   │   │-- integrations/\n│   │   │   │   │-- queue/\n│   │   │   │   │-- repositories/\n│   │   │   │-- usecases/\n│   │   │   │   │-- auth/\n│   │   │   │   │-- notification/\n│   │   │   │   │-- orders/\n│   │   │-- infrastructure/\n│   │   │   │-- config-env/\n│   │   │   │-- integrations/\n│   │   │   │-- queue/\n│   │   │   │-- repositories/\n│   │   │-- shared/\n│   │   │   │-- audit/\n│   │   │   │-- config/\n│   │-- test/\n│   │   │-- entrypoints/\n│   │   │   │-- web/\n│   │   │   │   │-- rest/\n```\n\n### **entrypoints**\n\nThe `entrypoints` module is responsible for managing the application's entry points, such as `web`, `jobs`, and\n`consumers`.\n\n**Important**: **It must not contain business logic**. This module may include input data validation for request\nobjects.\n\n### **core**\n\nThe `core` module manages all the application's business logic. Key guidelines include:\n\n- This module must be **autonomous** and **free of external dependencies**.\n  Do not use **external frameworks** or **libraries** directly in `core`.\n- The **domain** folder within the module contains the entities and granular business logic.\n- **Outgoing communication** to external systems must be handled through interfaces defined in the `providers` module.\n- **Incoming communication** must occur through interfaces in the `usecases` module.\n\n### **infrastructure**\n\nThe `infrastructure` module manages the application's external communication, such as:\n\n- **Database Connections**\n- **API Integrations**\n- **Messaging Systems**\n\n**Important**: The `infrastructure` module **must not contain business logic**.\n\n### **shared**\n\nThe `shared` module contains functionality and utilities that are shared between the **entrypoints** and\n**infrastructure**. It should be used to include functionality that does not involve business rules, such as validations\ninput, common error handling, and other external integration utilities.\n\n**Important**: The **core** layer must not use the `shared` module, as the business logic must remain\nindependent of external functionalities.\n\n\n## 2. Steps to Run the Project\n\n### 2.1. Starting the Project in Development Mode\n\nFollow the steps below to run the project in development mode.\n\n#### 2.1.1. Copy the configuration file:\n\n- We recommend creating an **alias** `dcli` to execute the command:  `docker compose -f docker-compose.cli.yml run --rm`\n\n```bash\n  chmod +x ./add_alias_cli.sh \u0026\u0026 ./add_alias_cli.sh\n```\n\n#### 2.1.2. Installing aws cli:\n\n- Install and configure [aws cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html):\n\n```bash\n  curl \"https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip\" -o \"awscliv2.zip\"\n  unzip awscliv2.zip\n  sudo ./aws/install\n```\n\n- Configuring AWS region:\n\n```bash\n  nano ~/.aws/config\n```\n\n```textmate\n[default]\nregion = us-east-1\noutput = json\n```\n\n- Configuring AWS credentials (optional):\n\n```bash\n  nano ~/.aws/credentials\n```\n\n```textmate\n[default]\naws_access_key_id = \u003caws_access_key_id\u003e\naws_secret_access_key =  \u003caws_secret_access_key\u003e\n```\n\n#### 2.1.3. Copy the configuration file:\n\n- Copy the `.env.dist` file to `.env` using the command:\n\n```bash\n  cp .env.dist .env\n```\n\n### 2.2. Start the project with Docker using the commands:\n\n- Creates the necessary Docker network:\n\n```bash\n  make create-network\n```\n\n- Builds Docker images:\n\n```bash\n  make build\n```\n\n- Installs project dependencies:\n\n```bash\n  make install\n```\n\n- Updates project dependencies:\n\n```bash\n  make upgrade-lib\n```\n\n- Seeds the database with initial data:\n\n```bash\n  make seed\n```\n\n- Starts the MongoDB container:\n\n```bash\n  make mongodb\n```\n\n- Starts the LocalStack container:\n\n```bash\n  make localstack-dev\n```\n\n- Creates queues in LocalStack:\n\n```bash\n  make create-queue-local\n```\n\n- Starts the application in development mode:\n\n```bash\n  make dev\n```\n\n- Runs lint and code formatting:\n\n```bash\n  make lint-format\n```\n\n- Automatically generates indices (if needed):\n\n```bash\n  make generate-index\n```\n\n- Automatically generates test file:\n\n```bash\n  make generate-test-file\n```\n\n- Runs test:\n\n```bash\n  make test\n```\n\n- Runs test with coverage:\n\n```bash\n  make test-coverage\n```\n\n- Run to add new dependency with `yarn`:\n\n```bash\n  dcli yarn add \u003cyour_dependency\u003e\n```\n\n### 2.3. Documentation\n\nThe project includes several forms of documentation accessible locally:\n\n- [Swagger UI - Interactive Interface](http://localhost:3000/swagger-doc)\n- [Swagger JSON - Swagger Document](http://localhost:3000/swagger-doc-json)\n- [Health Check - Application Health Verification](http://localhost:3000/health)\n\n#### 2.3.1. Diagrams\n\nFor a better understanding of the application's flow, refer to the diagrams below:\n\n- [Diagram](diagram/README.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhemicharly%2Fnestjs-api-architecture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhemicharly%2Fnestjs-api-architecture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhemicharly%2Fnestjs-api-architecture/lists"}