How md-redwan-hossain/nestjs-starter works
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