# niraj-khatiwada/ultimate-nestjs-boilerplate architecture

> Architecture diagram of the GitHub repository niraj-khatiwada/ultimate-nestjs-boilerplate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/niraj-khatiwada/ultimate-nestjs-boilerplate
- Repository: https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate

## Overview

1. This repository is a NestJS backend boilerplate built around a Fastify HTTP server, with a separate worker process for background jobs. The codebase is organized as a modular monolith: the main API app, shared infrastructure services, auth, and worker queues all live in the same repo but are split by module boundaries.

2. The primary external-facing surface is in `src/api`, which contains REST controllers, a GraphQL resolver, and WebSocket support. The `user` module is especially notable because it exposes both controller and resolver entry points, while `health` and `file` are REST-oriented. This means the architecture is multi-protocol rather than REST-only.

3. Authentication is handled by a dedicated `src/auth` subsystem built around Better Auth. It includes auth services, a guard, and persistence entities for users, sessions, accounts, passkeys, two-factor data, and verification records. The boundary here is important: business modules consume auth through guards/decorators rather than implementing login/session logic themselves.

4. Persistence is PostgreSQL via TypeORM. The database layer includes a `data-source`, migrations, seeds, and shared base model classes. The presence of entity and migration files indicates a schema-first backend where data shape is managed centrally and evolved through migrations rather than ad hoc runtime creation.

5. Configuration is heavily centralized under `src/config`. There are dedicated config modules for app runtime, database, auth, Redis, BullMQ, mail, AWS, Sentry, throttling, and Grafana. This suggests most infrastructure dependencies are injected through configuration factories and validated at startup rather than read directly in feature code.

6. Shared infrastructure lives under `src/shared` and `src/services`. Key services include Redis-backed caching, mail delivery, Socket.io gateway support, and AWS S3 file storage. The `aws` service is the explicit storage boundary for file uploads, while `cache` and `socket` show Redis being reused for both application caching and websocket scaling.

7. Background jobs are handled by BullMQ in a separate worker area under `src/worker`. The email queue has its own module, processor, service, event types, and queue constants, which implies the main API enqueues email tasks and the worker process consumes them asynchronously. That separation matters for architecture diagrams because job execution is not done in the request thread.

8. Email delivery is split between template generation and sending. React Email templates live in `src/shared/mail/templates`, while build-time scripts convert them into static artifacts consumed by the backend mail service. In development, Mailpit provides the SMTP inbox, so the flow is template source -> built email artifact -> mail service -> SMTP server.

9. Cross-cutting concerns are implemented as decorators, interceptors, middleware, and guards rather than inside feature modules. Examples include Sentry interception, file upload interception, basic auth middleware, public/optional auth decorators, current-user decorators, and custom validators. This indicates a framework-heavy design where request shaping and policy enforcement happen at the edge.

10. Rate limiting and observability are first-class infrastructure pieces. Throttling uses Redis-backed guards/factories, Sentry captures runtime errors, Pino is used for logging, and Prometheus/Grafana dashboards are provisioned for server and database metrics. Swagger setup is also included, which matters because it supports API documentation and frontend code generation.

11. Internationalization is built in with generated translation artifacts and locale files for English and Spanish. The `src/generated/i18n.generated.ts` file and translation JSONs show that message keys are managed centrally and compiled into app-ready resources.

12. The repo is designed for containerized deployment and operational tooling. Docker Compose files cover dev and prod, there is a separate Docker image for Mailpit, PM2 config is present for process management, and GitHub Actions plus a deploy script support CI/CD. Monitoring dashboards and email tooling are also bundled, reinforcing that this is meant as a production-ready starter rather than just an app skeleton.

13. In diagram terms, the main boundaries are: API entrypoints, auth/session boundary, database persistence layer, Redis-backed shared infrastructure, async worker boundary, and external services such as S3, SMTP, Sentry, and monitoring systems. Most feature flows pass through config/infrastructure modules before reaching the domain modules, which is the key structural pattern in this repo.

Main entry points: [`src/api/api.module.ts`](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/api/api.module.ts) (API module), [`src/app.module.ts`](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/app.module.ts) (App module), [`src/config/config.type.ts`](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/config/config.type.ts) (Config layer), [`src/api/user/user.module.ts`](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/api/user/user.module.ts) (User API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Surface"]
  node_api_module["API module<br/>feature aggregator<br/>[api.module.ts]"]
  node_user_api["User API<br/>multi-protocol feature<br/>[user.module.ts]"]
  node_health_api["Health API<br/>rest feature<br/>[health.module.ts]"]
  node_file_api["File API<br/>rest feature<br/>[file.module.ts]"]
end

subgraph group_auth["Auth Boundary"]
  node_auth_module["Auth module<br/>auth subsystem<br/>[auth.module.ts]"]
  node_auth_guard{{"Auth guard<br/>request guard<br/>[auth.guard.ts]"}}
  node_better_auth["Better Auth<br/>auth service"]
  node_user_entity[("Auth entities<br/>typeorm entities<br/>[user.entity.ts]")]
end

subgraph group_data["Persistence"]
  node_db_source[("DB source<br/>typeorm datasource<br/>[data-source.ts]")]
  node_db_models[("Base models<br/>entity base<br/>[base.model.ts]")]
  node_migrations["Migrations<br/>schema evolution"]
end

subgraph group_infra["Shared Infra"]
  node_app_module["App module<br/>bootstrap module<br/>[app.module.ts]"]
  node_main(("Main entry<br/>runtime bootstrap<br/>[main.ts]"))
  node_graphql_factory["GraphQL setup<br/>graphql config<br/>[graphql.factory.ts]"]
  node_socket_module["Socket module<br/>realtime infra<br/>[socket.module.ts]"]
  node_config_root["Config layer<br/>config modules<br/>[config.type.ts]"]
  node_shared_cache["Cache<br/>[cache.module.ts]"]
  node_shared_mail["Mail service<br/>delivery service<br/>[mail.module.ts]"]
  node_aws_service["S3 storage<br/>file storage<br/>[aws.module.ts]"]
  node_throttler{{"Throttling<br/>rate limit<br/>[throttler.guard.ts]"}}
  node_i18n["Translations<br/>localized resources<br/>[i18n.generated.ts]"]
end

subgraph group_worker["Async Worker"]
  node_email_worker["Email queue<br/>bullmq worker<br/>[email.module.ts]"]
end

subgraph group_ops["Operations"]
  node_ops_tools["Ops tooling<br/>observability/deploy"]
end

node_main -->|"bootstraps"| node_app_module
node_app_module -->|"loads"| node_api_module
node_app_module -->|"loads"| node_auth_module
node_app_module -->|"configures"| node_config_root
node_app_module -->|"connects"| node_db_source
node_api_module -->|"includes"| node_user_api
node_api_module -->|"includes"| node_health_api
node_api_module -->|"includes"| node_file_api
node_api_module -->|"enables"| node_graphql_factory
node_api_module -->|"enables"| node_socket_module
node_user_api -->|"protects"| node_auth_guard
node_user_api -->|"uses"| node_better_auth
node_user_api -->|"reads/writes"| node_user_entity
node_auth_module -->|"provides"| node_better_auth
node_auth_module -->|"provides"| node_auth_guard
node_auth_module -->|"persists"| node_user_entity
node_better_auth -->|"queries"| node_db_source
node_user_entity -->|"extends"| node_db_models
node_db_source -->|"evolves via"| node_migrations
node_config_root -->|"feeds"| node_shared_cache
node_config_root -->|"feeds"| node_shared_mail
node_config_root -->|"feeds"| node_aws_service
node_config_root -->|"feeds"| node_throttler
node_shared_mail -->|"enqueues/consumes"| node_email_worker
node_email_worker -->|"delivers"| node_shared_mail
node_shared_mail -.->|"attaches files"| node_aws_service
node_shared_cache -->|"scales"| node_socket_module
node_shared_cache -->|"backs"| node_throttler
node_i18n -->|"localizes"| node_api_module
node_ops_tools -.->|"observes"| node_app_module
node_ops_tools -.->|"observes"| node_db_source

click node_app_module "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/app.module.ts"
click node_main "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/main.ts"
click node_api_module "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/api/api.module.ts"
click node_user_api "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/api/user/user.module.ts"
click node_health_api "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/api/health/health.module.ts"
click node_file_api "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/api/file/file.module.ts"
click node_graphql_factory "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/graphql/graphql.factory.ts"
click node_socket_module "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/shared/socket/socket.module.ts"
click node_auth_module "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/auth/auth.module.ts"
click node_auth_guard "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/auth/auth.guard.ts"
click node_better_auth "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/auth/better-auth.service.ts"
click node_user_entity "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/auth/entities/user.entity.ts"
click node_db_source "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/database/data-source.ts"
click node_db_models "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/database/models/base.model.ts"
click node_migrations "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/database/migrations/1746266963361-init.ts"
click node_config_root "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/config/config.type.ts"
click node_shared_cache "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/shared/cache/cache.module.ts"
click node_shared_mail "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/shared/mail/mail.module.ts"
click node_aws_service "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/services/aws/aws.module.ts"
click node_throttler "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/config/throttler/throttler.guard.ts"
click node_i18n "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/generated/i18n.generated.ts"
click node_email_worker "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/worker/queues/email/email.module.ts"
click node_ops_tools "https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/tools/grafana/dashboards/server.dashboard.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_module,node_user_api,node_health_api,node_file_api toneBlue
class node_auth_module,node_auth_guard,node_better_auth,node_user_entity toneAmber
class node_db_source,node_db_models,node_migrations toneMint
class node_app_module,node_main,node_graphql_factory,node_socket_module,node_config_root,node_shared_cache,node_shared_mail,node_aws_service,node_throttler,node_i18n toneRose
class node_email_worker toneIndigo
class node_ops_tools toneTeal
```

## Components

### API Surface

HTTP, GraphQL, and WebSocket entrypoints

- [API module](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/api/api.module.ts): feature aggregator · Root module for public API features · `src/api/api.module.ts`
- [User API](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/api/user/user.module.ts): multi-protocol feature · User endpoints exposed via controller and resolver · `src/api/user/user.module.ts`
- [Health API](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/api/health/health.module.ts): rest feature · Service health endpoints · `src/api/health/health.module.ts`
- [File API](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/api/file/file.module.ts): rest feature · File upload and file-serving endpoints · `src/api/file/file.module.ts`

### Auth Boundary

Better Auth services and persistence

- [Auth module](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/auth/auth.module.ts): auth subsystem · Authentication composition around Better Auth · `src/auth/auth.module.ts`
- [Auth guard](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/auth/auth.guard.ts): request guard · Protects routes and mediates auth context · `src/auth/auth.guard.ts`
- [Better Auth](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/auth/better-auth.service.ts): auth service · Login, session, and account orchestration · `src/auth/better-auth.service.ts`
- [Auth entities](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/auth/entities/user.entity.ts): typeorm entities · Users, sessions, accounts, passkeys, and verification records · `src/auth/entities/user.entity.ts`

### Persistence

TypeORM database layer and schema evolution

- [DB source](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/database/data-source.ts): typeorm datasource · PostgreSQL connection and TypeORM setup · `src/database/data-source.ts`
- [Base models](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/database/models/base.model.ts): entity base · Shared model inheritance for persistence entities · `src/database/models/base.model.ts`
- [Migrations](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/database/migrations/1746266963361-init.ts): schema evolution · Versioned database changes and seed data · `src/database/migrations/1746266963361-init.ts`

### Shared Infra

Config, shared services, and cross-cutting framework pieces

- [App module](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/app.module.ts): bootstrap module · Top-level Nest application composition · `src/app.module.ts`
- [Main entry](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/main.ts): runtime bootstrap · Starts the HTTP server and app lifecycle · `src/main.ts`
- [GraphQL setup](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/graphql/graphql.factory.ts): graphql config · GraphQL runtime wiring and schema integration · `src/graphql/graphql.factory.ts`
- [Socket module](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/shared/socket/socket.module.ts): realtime infra · WebSocket gateway and Redis adapter · `src/shared/socket/socket.module.ts`
- [Config layer](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/config/config.type.ts): config modules · Centralized runtime and infrastructure configuration · `src/config/config.type.ts`
- [Cache](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/shared/cache/cache.module.ts): redis cache · Redis-backed application cache · `src/shared/cache/cache.module.ts`
- [Mail service](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/shared/mail/mail.module.ts): delivery service · Template rendering and outbound email delivery · `src/shared/mail/mail.module.ts`
- [S3 storage](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/services/aws/aws.module.ts): file storage · AWS S3 boundary for uploads and object storage · `src/services/aws/aws.module.ts`
- [Throttling](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/config/throttler/throttler.guard.ts): rate limit · Redis-backed request limiting · `src/config/throttler/throttler.guard.ts`
- [Translations](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/generated/i18n.generated.ts): localized resources · Generated and locale-specific message catalogs · `src/generated/i18n.generated.ts`

### Async Worker

Background job processing and queue execution

- [Email queue](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/worker/queues/email/email.module.ts): bullmq worker · Async email job processor and queue service · `src/worker/queues/email/email.module.ts`

### Operations

Deployment, observability, and container tooling

- [Ops tooling](https://github.com/niraj-khatiwada/ultimate-nestjs-boilerplate/blob/main/src/tools/grafana/dashboards/server.dashboard.json): observability/deploy · Docker, CI/CD, logging, metrics, and dashboards · `src/tools/grafana/dashboards/server.dashboard.json`

## Connections

- Main entry → App module: bootstraps · Runtime starts the Nest application composition
- App module → API module: loads · Application composition includes the public API surface
- App module → Auth module: loads · Application composition includes authentication
- App module → Config layer: configures · Central config is injected across the app
- App module → DB source: connects · App lifecycle initializes database access
- API module → User API: includes · User feature is part of the API surface
- API module → Health API: includes · Health endpoints are part of the API surface
- API module → File API: includes · File endpoints are part of the API surface
- API module → GraphQL setup: enables · GraphQL is wired into the API runtime
- API module → Socket module: enables · Realtime support is attached to the API runtime
- User API → Auth guard: protects · User operations rely on authentication guardrails
- User API → Better Auth: uses · User flows consume auth/session services
- User API → Auth entities: reads/writes · User flows persist auth-related records
- Auth module → Better Auth: provides · Auth module exposes Better Auth orchestration
- Auth module → Auth guard: provides · Auth module exports route protection
- Auth module → Auth entities: persists · Auth state is stored in dedicated entities
- Better Auth → DB source: queries · Auth service uses the TypeORM/PostgreSQL layer
- Auth entities → Base models: extends · Auth entities inherit shared persistence base models
- DB source → Migrations: evolves via · Schema is managed through migrations and seeds
- Config layer → Cache: feeds · Redis configuration supports shared cache and rate limiting
- Config layer → Mail service: feeds · Mail configuration drives outbound email delivery
- Config layer → S3 storage: feeds · AWS settings configure object storage access
- Config layer → Throttling: feeds · Throttling behavior is configured centrally
- Mail service → Email queue: enqueues/consumes · API mail flow delegates delivery jobs to the worker queue
- Email queue → Mail service: delivers · Worker consumes queued messages and sends mail
- Mail service → S3 storage: attaches files · Mail and file workflows can rely on shared storage services
- Cache → Socket module: scales · Redis backs websocket adapter coordination
- Cache → Throttling: backs · Redis is used for distributed rate limiting
- Translations → API module: localizes · API responses and messages use generated translations
- Ops tooling → App module: observes · Operational tooling monitors the running application
- Ops tooling → DB source: observes · Dashboards track database health and metrics