This is an advanced boilerplate project implementing Domain-Driven Design (DDD), Clean Architecture, CQRS (Command Query Responsibility Segregation), Event Sourcing and MongoDB with NestJS. It provides a robust foundation for building scalable and maintainable enterprise-level applications with proper separation of concerns and clean dependency direction.

If you want more documentation about NestJS, click here Nest

📝 Note: This version uses MongoDB with Mongoose. If you prefer the PostgreSQL version with TypeORM, you can find it at the original repository: https://github.com/CollatzConjecture/nestjs-clean-architecture-postgres

A quick introduction to clean architecture

• Clean Architecture: Enforces strict separation of concerns with proper dependency direction (Infrastructure → Application → Domain).
• Domain-Driven Design (DDD): Pure business logic encapsulated in Domain Services, accessed through Repository Interfaces.
• CQRS: Segregates read (Queries) and write (Commands) operations for optimized performance and scalability.
• Event Sourcing: Uses an event-driven approach with sagas for orchestrating complex business processes.
• Repository Pattern: Clean interfaces defined in Domain layer, implemented in Infrastructure layer.
• Dependency Inversion: Domain layer depends only on abstractions, never on concrete implementations.

• Domain Layer: Pure business logic, domain entities without framework dependencies, repository interfaces
• Application Layer: Business orchestration, application services, CQRS coordination, framework-agnostic services
• API Layer: HTTP controllers, DTOs, request/response handling, framework-specific HTTP concerns
• Infrastructure Layer: Database implementations, external API calls, concrete repository classes, global services

• JWT Authentication: Implements secure, token-based authentication with refresh token rotation.
• Google OAuth2 Integration: Secure third-party authentication with Google accounts, including CSRF protection.
• Role-Based Access Control (RBAC): Complete implementation with protected routes and role-based guards.
• Secure Password Storage: Hashes passwords using bcrypt with salt rounds.
• Sensitive Data Encryption: Encrypts sensitive fields (e.g., user emails) at rest in the database using AES-256-CBC.
• Blind Indexing: Allows for securely querying encrypted data without decrypting it first.
• CSRF Protection: OAuth flows protected against Cross-Site Request Forgery attacks using state parameters.

• MongoDB Integration: Utilizes Mongoose for structured data modeling with a NoSQL database.
• Containerized Environment: Full Docker and Docker Compose setup for development and production.
• Health Checks: Provides application health monitoring endpoints via Terminus.
• Structured Logging: Advanced logging system with business-context awareness and dependency injection.
• Application Metrics: Exposes performance metrics for Prometheus.
• Data Visualization: Comes with a pre-configured Grafana dashboard for visualizing metrics.
• Request Throttling: Built-in rate limiting to prevent abuse and ensure API stability.

• Unit & Integration Tests: A suite of tests for domain, application, and infrastructure layers.
• E2E Tests: End-to-end tests to ensure API functionality from request to response.
• High Test Coverage: Configured to report and maintain high code coverage.
• Mocking: Clear patterns for mocking database and service dependencies.

git clone https://github.com/CollatzConjecture/nestjs-clean-architecture
cd nestjs-clean-architecture

.
├── doc/
│   ├── common.http              # Common API requests
│   └── users.http               # User-specific API requests
├── src/
│   ├── api/                     # API Layer (HTTP Controllers & DTOs)
│   │   ├── controllers/
│   │   │   └── *.controller.ts  # HTTP endpoints (auth, profile, hello)
│   │   ├── dto/
│   │   │   ├── auth/            # Authentication DTOs
│   │   │   │   └── *.dto.ts     # Login & register DTOs
│   │   │   └── *.dto.ts         # Profile management DTOs
│   │   └── api.module.ts        # API module configuration
│   ├── application/             # Application Layer (Business Orchestration)
│   │   ├── __test__/
│   │   │   └── *.spec.ts        # Application layer tests
│   │   ├── auth/
│   │   │   ├── command/         # Auth commands & handlers
│   │   │   │   ├── *.command.ts # Create/delete auth user commands
│   │   │   │   └── handler/
│   │   │   │       └── *.handler.ts # Command handlers
│   │   │   ├── events/          # Auth domain events
│   │   │   │   └── *.event.ts   # User created/deleted events
│   │   │   ├── sagas/
│   │   │   │   └── *.saga.ts    # Registration flow orchestration
│   │   │   ├── decorators/
│   │   │   │   └── *.decorator.ts # Custom decorators (roles)
│   │   │   ├── guards/
│   │   │   │   └── *.guard.ts   # Authentication & authorization guards
│   │   │   ├── *.strategy.ts    # Auth strategies (JWT, local, Google OAuth)
│   │   │   └── auth.module.ts   # Auth module configuration
│   │   ├── decorators/
│   │   │   └── *.decorator.ts   # Global decorators (current user)
│   │   ├── interfaces/
│   │   │   └── *.interface.ts   # Application interfaces
│   │   ├── interceptors/
│   │   │   └── *.interceptor.ts # Request logging interceptors
│   │   ├── middlewere/
│   │   │   └── *.middleware.ts  # HTTP middleware (logging)
│   │   ├── services/
│   │   │   └── *.service.ts     # Application services (auth, profile, logger)
│   │   ├── profile/
│   │   │   ├── command/         # Profile commands & handlers
│   │   │   │   ├── *.command.ts # Profile commands
│   │   │   │   └── handler/
│   │   │   │       └── *.handler.ts # Command handlers
│   │   │   ├── events/          # Profile domain events
│   │   │   │   └── *.event.ts   # Profile events
│   │   │   └── profile.module.ts # Profile module configuration
│   │   └── application.module.ts # Application module aggregator
│   ├── domain/                  # Domain Layer (Pure Business Logic)
│   │   ├── __test__/
│   │   │   └── *.spec.ts        # Domain layer tests
│   │   ├── aggregates/          # Domain aggregates
│   │   ├── entities/
│   │   │   ├── *.ts             # Pure domain entities (Auth, Profile)
│   │   │   └── enums/           # Domain enums
│   │   │       └── *.enum.ts    # Role enums, etc.
│   │   ├── interfaces/
│   │   │   └── repositories/    # Repository contracts defined by domain
│   │   │       └── *.interface.ts # Repository interfaces
│   │   └── services/
│   │       └── *.service.ts     # Pure business logic services
│   ├── infrastructure/          # Infrastructure Layer (External Concerns)
│   │   ├── database/
│   │   │   ├── database.module.ts    # Database configuration
│   │   │   └── database.providers.ts # Database providers
│   │   ├── health/
│   │   │   └── *.check.ts       # Health check configurations
│   │   ├── logger/
│   │   │   └── logger.module.ts # Global logger module
│   │   ├── models/
│   │   │   ├── *.model.ts       # MongoDB models (auth, profile)
│   │   │   └── index.ts         # Model exports
│   │   └── repository/
│   │       └── *.repository.ts  # Repository implementations
│   ├── main.ts                  # Application entry point
│   ├── app.module.ts           # Root application module
│   └── constants.ts            # Application constants
├── test/
│   ├── *.e2e-spec.ts           # End-to-end tests
│   ├── jest-e2e.json           # E2E test configuration
│   └── setup-e2e.ts            # E2E test setup
├── prometheus/
│   └── prometheus.yml          # Prometheus configuration
├── docker-compose*.yml         # Docker Compose configurations (dev, prod)
└── Dockerfile                  # Container definition

This project follows a strict 4-layer architecture:

1. API Layer (src/api/): HTTP controllers, DTOs, and request/response handling
2. Application Layer (src/application/): Business orchestration, CQRS coordination, and application services
3. Domain Layer (src/domain/): Pure business logic, entities, and domain services
4. Infrastructure Layer (src/infrastructure/): Database, external services, and technical implementations

• ApiModule: Aggregates all HTTP controllers and imports ApplicationModule
• ApplicationModule: Central orchestrator that imports and exports feature modules
• AuthModule: Self-contained authentication feature with all its dependencies
• ProfileModule: Self-contained profile management feature with all its dependencies
• LoggerModule: Global infrastructure service for application-wide logging

• Commands: Handle write operations (Create, Update, Delete). Located in src/application/*/command.
• Queries: Handle read operations (Find, Get). Located in src/application/*/query.
• Handlers: Process commands and queries separately with proper business-context logging.
• Events: Publish domain events for side effects and inter-module communication.

1. User Registration:

   API Controller → Application Service → Domain Service (validation) →
   RegisterCommand → CreateAuthUser → AuthUserCreated Event →
   RegistrationSaga → CreateProfile → ProfileCreated
   

2. Authentication:

   API Controller → Application Service → Domain Service (email validation) →
   LoginCommand → ValidateUser → JWT Token Generation
   

3. Google OAuth Flow:

   /auth/google → Google OAuth → /auth/google/redirect →
   Domain Service (validation) → FindOrCreateUser → JWT Token Generation
   

4. Error Handling:

   ProfileCreationFailed Event → RegistrationSaga →
   DeleteAuthUser (Compensating Transaction)
   

• Feature Modules: Each feature (Auth, Profile) manages its own dependencies
• Domain Services: Injected via factories to maintain Clean Architecture principles
• Repository Pattern: Interfaces defined in domain, implementations in infrastructure
• Global Services: Logger provided globally via @Global() decorator

• Node.js 20+
• Docker and Docker Compose
• MongoDB (included in Docker Compose)
• Google OAuth2 credentials (for Google login functionality)

The project is configured to run seamlessly with Docker. Use the pnpm scripts from package.json for convenience.

# Build and start containers in detached mode for development
$ pnpm run docker:dev

# Build and start containers for production
$ pnpm run docker:prod

# View logs for the API service
$ pnpm run docker:logs

# Stop all running containers
$ pnpm run docker:down

# Restart the development environment
$ pnpm run docker:restart

• Application: http://localhost:4000
• API Documentation (Swagger): http://localhost:4000/api
• MongoDB: localhost:27017
• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000 (admin/admin)

$ pnpm install

# Development
$ pnpm run start

# Watch mode (recommended for development)
$ pnpm run start:dev

# Production mode
$ pnpm run start:prod

# Debug mode
$ pnpm run start:debug

# Unit tests
$ pnpm run test

# E2E tests
$ pnpm run test:e2e

# Test coverage
$ pnpm run test:cov

# Watch mode
$ pnpm run test:watch

# Check code style
$ pnpm run lint

# Auto-fix issues where possible
$ pnpm run lint:fix

You can import this Postman collection to test the API endpoints.

The collection includes:

• Authentication endpoints: Register, login, logout, Google OAuth
• Profile management: Create, read, update profile data
• Protected routes: Examples with JWT token authentication
• Admin endpoints: Role-based access control examples
• Environment variables: Pre-configured for localhost development

1. Import the collection: Download and import NestJS CA-DDD.postman_collection.json into Postman
2. Set environment variables: Configure the following variables in Postman:
   • localhost: http://localhost (or your host)
   • port: 4000 (or your configured port)
   • Authorization: Bearer <your-jwt-token> (set after login)
3. Test the flow:
   • Start with user registration
   • Login to get JWT token
   • Use the token for protected endpoints

POST /auth/register       # User registration
POST /auth/login          # User login
POST /auth/logout         # User logout (Protected)
POST /auth/refresh-token  # Token refresh (Protected)
GET  /auth/google         # Initiate Google OAuth login
GET  /auth/google/redirect # Google OAuth callback
GET  /auth/:id            # Get user by auth ID (Protected)
DELETE /auth/:id          # Delete user by auth ID (Protected)

GET  /profile/all         # Get all user profiles (Admin only)
GET  /profile/admins      # Get all admin users (Admin only)
GET  /profile/:id         # Get user profile by ID
POST /profile             # Create a new profile

GET  /hello               # Health check endpoint
GET  /health              # Detailed health check
GET  /metrics             # Prometheus metrics

# Register a new user
curl -X POST http://localhost:4000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John",
    "lastname": "Doe",
    "age": 30,
    "email": "[email protected]",
    "password": "securePassword123"
  }'

# Login
curl -X POST http://localhost:4000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securePassword123"
  }'

# Initiate Google login (redirects to Google)
curl -X GET http://localhost:4000/auth/google

# The callback is handled automatically after Google authentication
# Returns JWT token upon successful authentication

# Access protected route
curl -X GET http://localhost:4000/profile/123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Admin-only route
curl -X GET http://localhost:4000/profile/all \
  -H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN"

• NestJS - Progressive Node.js framework
• TypeScript - Type-safe JavaScript

• @nestjs/cqrs - CQRS implementation
• @nestjs/event-emitter - Event handling

• @nestjs/jwt - JWT implementation
• @nestjs/passport - Authentication strategies
• @nestjs/throttler - Rate limiting
• bcrypt - Password hashing
• cookie-parser - Cookie handling for OAuth state

• Mongoose - MongoDB object modeling
• MongoDB - Document database

• @nestjs/terminus - Health checks
• Prometheus - Metrics collection
• Grafana - Metrics visualization

• Jest - Testing framework
• Supertest - HTTP assertion library

• Nodemon - Development server
• Docker - Containerization

• Authentication Context: User login, registration, tokens, OAuth integration
• Profile Context: User profile management, personal data

• UserAggregate: Manages user lifecycle and events across auth and profile contexts

• AuthUserCreatedEvent: Triggered after successful user creation
• AuthUserDeletedEvent: Triggered when user is deleted (compensating action)
• ProfileCreationFailedEvent: Triggered when profile creation fails

• RegistrationSaga: Orchestrates user registration process
  • Handles profile creation after auth user creation
  • Implements compensating transactions for failures
  • Supports both traditional and OAuth registration flows

• Business-Context Logging: Logs focus on business events rather than technical execution
• Dependency Injection: Logger service is injected throughout the application
• Consistent Format: All logs include module, method, and timestamp information
• Security Audit Trail: Comprehensive logging of authentication attempts and outcomes

• Database connectivity
• Memory usage
• Disk space

• HTTP request duration
• Request count by endpoint
• Error rates
• Database connection pool
• Authentication success/failure rates

• Application performance metrics
• Database statistics
• Error tracking
• Response time analysis
• Authentication analytics

1. Clone the repository:

   git clone https://github.com/CollatzConjecture/nestjs-clean-architecture
   cd nestjs-clean-architecture

2. Create an environment file:

   Create a file named .env in the root of the project by copying the example file.

   cp .env.example .env

3. Generate Secrets:

   Your .env file requires several secret keys to run securely. Use the following command to generate a cryptographically strong secret:

   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

   Run this command for each of the following variables in your .env file and paste the result:

   • JWT_SECRET
   • JWT_REFRESH_SECRET
   • EMAIL_ENCRYPTION_KEY
   • EMAIL_BLIND_INDEX_SECRET

   Do not use the same value for different keys.

4. Configure Google OAuth2 (Optional):

   To enable Google login functionality, you'll need to:

   a. Go to the Google Cloud Console

   b. Create a new project or select an existing one

   c. Enable the Google+ API

   d. Create OAuth 2.0 credentials (Web application type)

   e. Add your redirect URI: http://localhost:4000/auth/google/redirect

   f. Add the following to your .env file:

   GOOGLE_CLIENT_ID=your_google_client_id_here
   GOOGLE_CLIENT_SECRET=your_google_client_secret_here
   GOOGLE_CALLBACK_URL=http://localhost:4000/auth/google/redirect

• JWT with Refresh Tokens: Secure token-based authentication with automatic refresh
• Password Security: Bcrypt hashing with configurable salt rounds
• OAuth2 Security: CSRF protection using state parameters in OAuth flows
• Rate Limiting: Configurable throttling on sensitive endpoints

• Encryption at Rest: Sensitive data encrypted using AES-256-CBC
• Blind Indexing: Secure querying of encrypted data
• Input Validation: Comprehensive DTO validation using class-validator
• SQL Injection Prevention: MongoDB with Mongoose provides built-in protection
• Automatic Timestamps: All models include createdAt and updatedAt for audit trails

• Role-Based Authorization: Complete RBAC implementation with guards
• Route Protection: JWT guards on sensitive endpoints
• Admin Controls: Separate endpoints for administrative functions

• Jerry Lucas - Current Maintainer - GitHub

This project is licensed under the MIT License - see the LICENSE file for details.

• Edwin Caminero - Inspiration for this project
• Clean Architecture principles by Robert C. Martin
• Domain-Driven Design concepts by Eric Evans
• CQRS and Event Sourcing patterns
• NestJS framework and community

• Clean Architecture
• Domain-Driven Design
• CQRS Pattern
• Event Sourcing
• NestJS Documentation
• OAuth 2.0 Security Best Practices
• Repository Pattern
• Dependency Inversion Principle