niraj-khatiwada/ultimate-nestjs-boilerplate

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.