# sensitiky/nest-microservices-boilerplate architecture

> Architecture diagram of the GitHub repository sensitiky/nest-microservices-boilerplate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sensitiky/nest-microservices-boilerplate
- Repository: https://github.com/sensitiky/nest-microservices-boilerplate

## Overview

##### Project Type and Purpose
- This is a NestJS‑based microservices boilerplate that implements a hexagonal (ports & adapters) architecture.
- It provides four discrete services—Gateway, Auth, User, Product—plus shared libraries (Common, Config) to handle cross‑cutting concerns like DTOs, entities, database connection, guards, and interceptors.

##### High‑Level File Structure Analysis
- apps/
- gateway/ (API Gateway)
- auth/ (Authentication service)
- user/ (User management service)
- product/ (Product management service)
- libs/
- common/ (shared DTOs & entities)
- config/ (database modules, guards, interceptors)
- docker-compose.yml & docker‑scripts/ (container orchestration & multi‑DB setup)
- Root configs: nest‑cli.json, tsconfig.*, package.json

##### Key Insights from README
- Each microservice follows the hexagonal pattern with three layers:
- Domain: entities, port interfaces (repositories, service interfaces)
- Application: implements use‑cases via domain ports
- Infrastructure: NestJS controllers, ORM entity definitions, repository implementations
- Gateway routes incoming HTTP requests to the appropriate microservice.
- Shared libs hold common DTOs/entities and global configuration (DB connection, guards, interceptors).

a. Main Components
- Clients (Browser, Mobile App, CLI)
- API Gateway (apps/gateway)
- Microservices: Auth, User, Product (apps/auth, apps/user, apps/product)
- Databases: one PostgreSQL instance hosting multiple schemas/DBs (per microservice)
- Shared Libraries: Common, Config
- Docker Compose / Container Network

b. Relationships & Interactions
1. Clients → HTTP → API Gateway
2. API Gateway → (HTTP or TCP RPC) → Auth/User/Product services
3. Each microservice → ORM → its own PostgreSQL schema/DB
4. All services import libs/common and libs/config modules at compile time
5. Docker Compose orchestrates network links among containers

c. Architectural Patterns & Principles
- Hexagonal Architecture within each microservice (Ports & Adapters)
- Microservices pattern: independently deployable, scoped by business domain
- API Gateway pattern: central routing, composition of downstream services
- Shared‑library pattern: avoid duplication for DTOs, entities, and common config

d. Core Technologies & Frameworks
- NestJS (framework)
- TypeScript (language)
- Bun or Node.js (runtime)
- PostgreSQL (relational database)
- Docker & Docker Compose (containerization)
- Scripts to create multiple DBs (docker‑scripts/create‑multiple‑postgresql‑databases.sh)

##### Diagramming Conventions
- Gray for shared libraries
- Rectangles for services/components
- Rounded rectangles for libraries/modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    Clients(["Clients\n(Browser, Mobile, CLI)"]):::external
    Clients --> Gateway["API Gateway"]:::service

    subgraph "Docker Compose Network"
        direction TB

        subgraph "Gateway Service"
            direction TB
            GW_Domain["Domain Layer"]:::layer
            GW_App["Application Layer"]:::layer
            GW_Infra["Infrastructure Layer"]:::layer
        end
        Gateway --> GW_Domain
        Gateway --> GW_App
        Gateway --> GW_Infra

        Gateway --> AuthS["Auth Service"]:::service
        subgraph "Auth Service"
            direction TB
            Auth_Domain["Domain Layer"]:::layer
            Auth_App["Application Layer"]:::layer
            Auth_Infra["Infrastructure Layer"]:::layer
        end
        AuthS --> Auth_Domain
        AuthS --> Auth_App
        AuthS --> Auth_Infra

        Gateway --> UserS["User Service"]:::service
        subgraph "User Service"
            direction TB
            User_Domain["Domain Layer"]:::layer
            User_App["Application Layer"]:::layer
            User_Infra["Infrastructure Layer"]:::layer
        end
        UserS --> User_Domain
        UserS --> User_App
        UserS --> User_Infra

        Gateway --> ProductS["Product Service"]:::service
        subgraph "Product Service"
            direction TB
            Prod_Domain["Domain Layer"]:::layer
            Prod_App["Application Layer"]:::layer
            Prod_Infra["Infrastructure Layer"]:::layer
        end
        ProductS --> Prod_Domain
        ProductS --> Prod_App
        ProductS --> Prod_Infra

        Auth_Infra --> Postgres["PostgreSQL DB"]:::db
        User_Infra --> Postgres
        Prod_Infra --> Postgres
    end

    libs_common["libs/common"]:::lib
    libs_config["libs/config"]:::lib

    libs_common -.-> GW_App
    libs_common -.-> Auth_App
    libs_common -.-> User_App
    libs_common -.-> Prod_App

    libs_config -.-> GW_Infra
    libs_config -.-> Auth_Infra
    libs_config -.-> User_Infra
    libs_config -.-> Prod_Infra

    click Gateway "https://github.com/sensitiky/nest-microservices-boilerplate/tree/master/apps/gateway"
    click GW_Domain "https://github.com/sensitiky/nest-microservices-boilerplate/blob/master/apps/gateway/src/domain/services/gateway.service.interface.ts"
    click GW_App "https://github.com/sensitiky/nest-microservices-boilerplate/blob/master/apps/gateway/src/application/services/gateway.service.ts"
    click GW_Infra "https://github.com/sensitiky/nest-microservices-boilerplate/blob/master/apps/gateway/src/infrastructure/controllers/gateway.controller.ts"
    click AuthS "https://github.com/sensitiky/nest-microservices-boilerplate/tree/master/apps/auth"
    click Auth_Domain "https://github.com/sensitiky/nest-microservices-boilerplate/blob/master/apps/auth/src/domain/services/auth.service.interface.ts"
    click Auth_App "https://github.com/sensitiky/nest-microservices-boilerplate/blob/master/apps/auth/src/application/services/auth.service.ts"
    click Auth_Infra "https://github.com/sensitiky/nest-microservices-boilerplate/blob/master/apps/auth/src/infrastructure/controllers/auth.controller.ts"
    click UserS "https://github.com/sensitiky/nest-microservices-boilerplate/tree/master/apps/user"
    click User_Domain "https://github.com/sensitiky/nest-microservices-boilerplate/blob/master/apps/user/src/domain/services/user.service.interface.ts"
    click User_App "https://github.com/sensitiky/nest-microservices-boilerplate/blob/master/apps/user/src/application/services/user.service.ts"
    click User_Infra "https://github.com/sensitiky/nest-microservices-boilerplate/blob/master/apps/user/src/infrastructure/controllers/user.controller.ts"
    click ProductS "https://github.com/sensitiky/nest-microservices-boilerplate/tree/master/apps/product"
    click Prod_Domain "https://github.com/sensitiky/nest-microservices-boilerplate/blob/master/apps/product/src/domain/services/product.service.interface.ts"
    click Prod_App "https://github.com/sensitiky/nest-microservices-boilerplate/blob/master/apps/product/src/application/services/product.service.ts"
    click Prod_Infra "https://github.com/sensitiky/nest-microservices-boilerplate/blob/master/apps/product/src/infrastructure/controllers/product.controller.ts"
    click libs_common "https://github.com/sensitiky/nest-microservices-boilerplate/tree/master/libs/common"
    click libs_config "https://github.com/sensitiky/nest-microservices-boilerplate/tree/master/libs/config"

    classDef service fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef layer fill:#FFA500,stroke:#000,stroke-width:1px
    classDef db fill:#90EE90,stroke:#000,stroke-width:1px
    classDef lib fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#000,stroke-width:1px
```
