# md-redwan-hossain/nestjs-starter architecture

> Architecture diagram of the GitHub repository md-redwan-hossain/nestjs-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/md-redwan-hossain/nestjs-starter
- Repository: https://github.com/md-redwan-hossain/nestjs-starter

## Overview

##### Project Type & Purpose
- This is a monolithic, backend-only NestJS application following a modular, layered architecture (no separate frontend).
- Purpose: Expose REST APIs with full admin (“Stuff”) management, authentication, caching, queueing, logging, health checks, and email sending.

##### File Structure
- **Top-Level Config & Orchestration**
- docker-compose.yaml: spins up PostgreSQL, MongoDB, Redis
- drizzle.config.ts, nest-cli.json: build/migration configs
- .env.example, .env.migrator.example: environment variables
- **src/configs**: central configuration for BullMQ, cache, JWT, Mongoose, throttling
- **src/modules** (three layers)
- business-layer: domain modules (e.g., user-management)
- data-layer: Drizzle ORM decorator, schema, relations against PostgreSQL
- internal-layer: cross-cutting concerns (auth, cryptography, email-sender, health-checker, logging)
- **src/shared**: common DTOs, decorators, pipes, exception filters, helpers, constants
- **db**: raw SQL migrations (DbMate) and schema snapshots
- **package.json**: SWC compiler, NestJS, Drizzle, BullMQ, Swagger

##### Key Technologies & External Services
- HTTP/REST API via NestJS (TypeScript → SWC compiler)
- PostgreSQL (primary data store) accessed via Drizzle ORM
- MongoDB (structured logging) via Mongoose
- Redis (cache, throttling, JWT blacklist, queue transport)
- BullMQ (queueing) for background email tasks
- Mailgun (external email-sending service)
- Swagger UI (/api-doc)

##### Main Components & Their Interactions
A. Client Layer
- HTTP clients, Swagger UI
B. NestJS Application
1. HTTP Gateway (Controllers + Guards + Custom Decorators)
- JwtAuthGuard, RoleGuard, AllowedRoles, JwtRbacAuth
2. Application Services
- business-layer services (e.g., UserManagementService)
- internal services (AuthService, TwoFactorAuthService, CryptographyService, EmailSenderService, LoggingService)
3. Data Access
- Repositories (Drizzle + custom repository classes)
- Mongoose models for logs
4. Infrastructure Integrations
- CacheModule (Redis)
- ThrottlerModule (Redis)
- BullMQModule (Redis queues)
- Mailgun adapter
- HealthCheckerModule
C. External Systems
- PostgreSQL DB
- MongoDB
- Redis Cluster
- Mailgun API

1. Client → HTTP Gateway → Controllers
2. Guards/Decorators intercept → Authentication/Authorization → Controller
3. Controller → Service → Repository → PostgreSQL (Drizzle)
4. LoggingService → MongoDB
5. CacheModule ↔ Redis (read/write)
6. ThrottlerModule ↔ Redis
7. JWT blacklist ↔ Redis
8. EmailSenderService enqueues jobs to BullMQ (via Redis)
9. BullMQ worker picks jobs → Mailgun API
10. HealthChecker probes DBs and Reports via /health endpoint

##### Architectural Patterns & Design Principles
- **Layered Architecture**: clear separation between presentation (controllers), business logic (services), and data access (repositories).
- **SOLID / Dependency Injection**: each module is self-contained, injected via NestJS modules
- **Modularization**: separate “business-layer”, “data-layer”, “internal-layer”, “shared”
- **Event-Driven / Queueing**: BullMQ for asynchronous tasks (email sending)
- **Circuit Breakers & Throttling**: Redis for rate-limiting

##### Final Checklist
- All NestJS modules (business, data, internal, shared) and their interdependencies
- External systems (Postgres, MongoDB, Redis, Mailgun)
- Data flows (HTTP, SQL, Redis, queue) with arrowed lines
- Clear, descriptive labels

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration & Config
    subgraph "Orchestration & Config"
        DC["Docker Orchestration"]:::external
        DC --> Postgres
        DC --> MongoDB
        DC --> Redis
        Mgr["Migration & ORM Config"]:::external
        Mgr --> Postgres
    end

    %% Client Layer
    Client["HTTP Client / Swagger UI"]:::external

    %% NestJS Application
    subgraph "NestJS Application"
        direction TB
        %% HTTP Gateway
        subgraph "HTTP Gateway"
            direction TB
            UMC["UserManagementController"]:::nest
            HCC["HealthCheckerController"]:::nest
            JG["JwtAuthGuard"]:::nest
            RG["RoleGuard"]:::nest
        end

        %% Application Services
        subgraph "Application Services"
            direction TB
            UMS["UserManagementService"]:::nest
            AS["AuthService"]:::nest
            TFAS["TwoFactorAuthService"]:::nest
            CS["CryptographyService"]:::nest
            ESS["EmailSenderService"]:::nest
            LS["LoggingService"]:::nest
        end

        %% Data Access
        subgraph "Data Access"
            direction TB
            UMR["UserManagementRepository"]:::nest
            MLM["MongoLogModel"]:::nest
        end

        %% Infrastructure Integrations
        subgraph "Infrastructure Integrations"
            direction TB
            CM["CacheModule (Redis)"]:::cache
            TM["ThrottlerModule (Redis)"]:::cache
            BQ["BullMQModule"]:::cache
            MA["Mailgun Adapter"]:::external
            HM["HealthCheckerModule"]:::nest
        end
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        Postgres[(PostgreSQL)]:::datastore
        MongoDB[(MongoDB)]:::datastore
        Redis[(Redis)]:::cache
        MailgunAPI[(Mailgun API)]:::external
    end

    %% Data Flows
    Client -->|"HTTP/REST"| UMC
    UMC -->|uses Guard| JG
    UMC -->|uses Guard| RG
    UMC -->|calls Service| UMS
    UMC -->|calls Service| HM
    HCC -->|calls Module| HM

    UMS -->|SQL| UMR
    UMR -->|reads/writes| Postgres

    LS -->|logs| MLM
    MLM -->|writes| MongoDB

    CM <-->|read/write| Redis
    TM <-->|rate-limit| Redis

    AS -->|JWT blacklist| Redis

    ESS -->|enqueue| BQ
    BQ -->|queue via| Redis
    BQ -->|worker calls| MA
    MA -->|HTTP| MailgunAPI

    HM -->|health-probe| Postgres
    HM -->|health-probe| MongoDB
    HM -->|health-probe| Redis

    %% Click Events
    click DC "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/docker-compose.yaml"
    click Mgr "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/drizzle.config.ts"
    click Mgr "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/nest-cli.json"
    click UMC "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/src/modules/business-layer/user-management/user-management.controller.ts"
    click UMS "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/src/modules/business-layer/user-management/user-management.service.ts"
    click UMR "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/src/modules/business-layer/user-management/user-management.repository.ts"
    click JG "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/src/modules/internal-layer/auth/guards/jwt-auth.guard.ts"
    click RG "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/src/modules/internal-layer/auth/guards/role.guard.ts"
    click AS "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/src/modules/internal-layer/auth/services/jwt-auth.service.ts"
    click TFAS "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/src/modules/internal-layer/auth/services/two-factor-auth.service.ts"
    click CS "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/src/modules/internal-layer/cryptography/cryptography.service.ts"
    click ESS "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/src/modules/internal-layer/email-sender/email-sender.service.ts"
    click BQ "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/src/modules/internal-layer/email-sender/queues/account-verification-email-sender.queue.ts"
    click HM "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/src/modules/internal-layer/health-checker/health-checker.module.ts"
    click HCC "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/src/modules/internal-layer/health-checker/health-checker.controller.ts"
    click LS "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/src/modules/internal-layer/logging/logging.service.ts"
    click MLM "https://github.com/md-redwan-hossain/nestjs-starter/blob/main/src/modules/internal-layer/logging/logging.entity.ts"

    %% Styles
    classDef nest fill:#DDEEFF,stroke:#0000CC,color:#000
    classDef datastore fill:#DFFFD4,stroke:#006400,color:#000
    classDef cache fill:#FFE4B5,stroke:#FF8C00,color:#000
    classDef external fill:#E8D1F0,stroke:#800080,color:#000
```
