NestJS Clean Architecture with DDD, CQRS & Event Sourcing

This is an advanced boilerplate project implementing Domain-Driven Design (DDD), Clean Architecture, CQRS (Command Query Responsibility Segregation), Event Sourcing and PostgreSQL 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 PostgreSQL with TypeORM. If you prefer the MongoDB version with Mongoose, you can find it at the original repository: https://github.com/CollatzConjecture/nestjs-clean-architecture

A quick introduction to clean architecture

🚀 Features

Core 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.

Proper Layer Separation

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

Security & Authentication

JWT Authentication: Implements secure, token-based authentication with refresh token rotation.
Google OAuth2 Integration: Secure third-party authentication with Google accounts for both web and mobile applications.
Apple Sign In: Native Sign in with Apple support for iOS and Android clients using Apple ID tokens.
Web OAuth2: Traditional OAuth2 flow with CSRF protection using state parameters and browser redirects.
Mobile OAuth2: Direct token exchange for mobile applications using Google ID tokens.
JWKS-Based Token Validation: Uses remote JSON Web Key Sets (JWKS) for signature verification of Google and Apple ID tokens.
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.

Infrastructure & Operations

PostgreSQL Integration: Utilizes TypeORM for structured data modeling with a relational 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.

Testing

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.

Getting Started

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

📁 Project Structure

.
├── 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
│   │   ├── entities/
│   │   │   ├── *.entity.ts      # PostgreSQL entities (auth, profile)
│   │   │   └── index.ts         # Entity 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

🏗️ Architecture Overview

Layer Architecture

This project follows a strict 4-layer architecture:

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

Module Structure

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

CQRS Implementation

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.

Event-Driven Flow

User Registration:

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

Authentication:

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

Google OAuth Flow (Web):

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

Google OAuth Flow (Mobile - iOS):

/auth/google/mobile/ios → ID Token Validation →
Domain Service (validation) → FindOrCreateUser → JWT Token Generation

Google OAuth Flow (Mobile - Android):

/auth/google/mobile/android → ID Token Validation →
Domain Service (validation) → FindOrCreateUser → JWT Token Generation

Apple Sign In Flow (Mobile):

/auth/mobile/apple → Apple ID Token Validation via JWKS →
Domain Service (validation) → FindOrCreateUser → JWT Token Generation

Error Handling:

ProfileCreationFailed Event → RegistrationSaga →
DeleteAuthUser (Compensating Transaction)

Dependency Injection & Module Boundaries

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

📋 Prerequisites

Node.js 20+
Docker and Docker Compose
PostgreSQL (included in Docker Compose)
Google OAuth2 credentials (for Google login functionality)
Apple Sign In credentials (for Apple login functionality)

🐳 Running with Docker Compose

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

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

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

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

# Stop all running containers
$ npm run docker:down

# Restart the development environment
$ npm run docker:restart

🌐 Service Access

Application: http://localhost:4000
API Documentation (Swagger): http://localhost:4000/api
PostgreSQL: localhost:5432
Prometheus: http://localhost:9090
Grafana: http://localhost:3000 (admin/admin)

📦 Installation

$ npm install

🚀 Running the Application

# Development
$ npm run start

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

# Production mode
$ npm run start:prod

# Debug mode
$ npm run start:debug

🧪 Testing

# Unit tests
$ npm run test

# E2E tests
$ npm run test:e2e

# Test coverage
$ npm run test:cov

# Watch mode
$ npm run test:watch

🔐 API Endpoints

Authentication

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 (Web)
GET  /auth/google/oauth2redirect  # Google OAuth callback (Web)
POST /auth/google/mobile/ios     # Google OAuth login for iOS apps
POST /auth/google/mobile/android # Google OAuth login for Android apps
POST /auth/mobile/apple          # Apple Sign In for mobile apps (iOS/Android)
GET  /auth/:id              # Get user by auth ID (Protected)
DELETE /auth/:id            # Delete user by auth ID (Protected)

Profile Management (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

Health & Monitoring

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

Example Usage

Traditional Registration & Login

# 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"
  }'

Google OAuth Login

Web OAuth Flow

# 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

Mobile OAuth Flow

iOS Authentication:

# iOS Google login with ID token
curl -X POST http://localhost:4000/auth/google/mobile/ios \
  -H "Content-Type: application/json" \
  -d '{
    "idToken": "GOOGLE_ID_TOKEN_FROM_IOS_APP"
  }'

# Returns JWT token upon successful authentication

Android Authentication:

# Android Google login with ID token
curl -X POST http://localhost:4000/auth/google/mobile/android \
  -H "Content-Type: application/json" \
  -d '{
    "idToken": "GOOGLE_ID_TOKEN_FROM_ANDROID_APP"
  }'

# Returns JWT token upon successful authentication

Apple Sign In

# Apple login with ID token
curl -X POST http://localhost:4000/auth/mobile/apple \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "ios",
    "idToken": "APPLE_ID_TOKEN_FROM_CLIENT"
  }'

# Returns JWT token upon successful authentication

Protected Routes

# 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"

🛠️ Built With

Core Framework

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

Architecture & Patterns

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

Authentication & Security

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

Database & Storage

TypeORM - PostgreSQL object relational mapping
PostgreSQL - Relational database

Monitoring & Health

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

Testing

Jest - Testing framework
Supertest - HTTP assertion library

Development Tools

Nodemon - Development server
Docker - Containerization

🏛️ Domain-Driven Design

Bounded Contexts

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

Aggregates

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

Domain Events

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

Sagas

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

📈 Monitoring & Observability

Structured Logging

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

Health Checks

Database connectivity
Memory usage
Disk space

Metrics (Prometheus)

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

Dashboards (Grafana)

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

⚙️ Configuration

Clone the repository:

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

Create an environment file:

Create a file named .env in the root of the project by copying the example file.
```
cp .env.example .env
```
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.
Configure Google OAuth2 (Optional):

To enable Google login functionality for both web and mobile applications, 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 for web OAuth flow
- Android/iOS application type for mobile OAuth flow (if using native mobile apps)
e. For web OAuth, add your redirect URI: http://localhost:4000/auth/google/oauth2redirect

f. Add the following to your .env file:
```
# Web OAuth credentials
GOOGLE_CLIENT_ID=your_google_client_id_here
GOOGLE_CLIENT_SECRET=your_google_client_secret_here
GOOGLE_CALLBACK_URL=http://localhost:4000/auth/google/oauth2redirect

# Mobile OAuth credentials (platform-specific)
GOOGLE_IOS_CLIENT_ID=your_ios_client_id_here
GOOGLE_ANDROID_CLIENT_ID=your_android_client_id_here
GOOGLE_MOBILE_CALLBACK_IOS_URL=your_ios_callback_url_here
GOOGLE_MOBILE_CALLBACK_ANDROID_URL=your_android_callback_url_here
```
Note for Mobile Apps:
- iOS: Use Google Sign-In SDK for iOS to obtain ID tokens, then send to /auth/google/mobile/ios
- Android: Use Google Sign-In SDK for Android to obtain ID tokens, then send to /auth/google/mobile/android
- The backend validates these ID tokens without requiring client secrets
- Platform-specific client IDs provide additional validation and security
Configure Apple Sign In (Optional):

To enable Sign in with Apple for your mobile applications:

a. Sign in to the Apple Developer portal

b. Create an App Identifier that supports Sign in with Apple for each platform bundle ID

c. Generate a Services ID for web/mobile authentication and enable Sign in with Apple

d. Create a private key (p8 file) associated with the Sign in with Apple service

e. Add the following variables to your .env file:
```
APPLE_TEAM_ID=your_apple_team_id
APPLE_KEY_ID=your_key_id
APPLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
APPLE_IOS_CLIENT_ID=your_ios_service_id
APPLE_ANDROID_CLIENT_ID=your_android_service_id
# Optional comma-separated list of additional audience values
APPLE_IOS_ADDITIONAL_AUDIENCES=
APPLE_ANDROID_ADDITIONAL_AUDIENCES=
```
f. Provide the corresponding platform value (ios or android) and the Apple ID token from the client when calling /auth/mobile/apple.

🔒 Security Features

Authentication Security

JWT with Refresh Tokens: Secure token-based authentication with automatic refresh
Password Security: Bcrypt hashing with configurable salt rounds
OAuth2 Security:
- Web: CSRF protection using state parameters in OAuth flows
- Mobile: Direct ID token validation for mobile applications
- JWKS Validation: All Google and Apple ID tokens are verified against their official JWKS endpoints before trust
Apple Sign In: Supports native Sign in with Apple flows for iOS and Android using platform-specific audiences
Rate Limiting: Configurable throttling on sensitive endpoints

Data Protection

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: PostgreSQL with TypeORM provides built-in protection
Automatic Timestamps: All models include createdAt and updatedAt for audit trails

Access Control

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

👨‍💻 Authors

Jerry Lucas - Current Maintainer - GitHub

📄 License

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

🙏 Acknowledgments

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

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
doc		doc
prometheus		prometheus
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
nest-cli.json		nest-cli.json
nodemon-debug.json		nodemon-debug.json
nodemon.json		nodemon.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

License

CollatzConjecture/nestjs-clean-architecture-postgres

Folders and files

Latest commit

History

Repository files navigation

NestJS Clean Architecture with DDD, CQRS & Event Sourcing

🚀 Features

Core Architecture

Proper Layer Separation

Security & Authentication

Infrastructure & Operations

Testing

Getting Started

📁 Project Structure

🏗️ Architecture Overview

Layer Architecture

Module Structure

CQRS Implementation

Event-Driven Flow

Dependency Injection & Module Boundaries

📋 Prerequisites

🐳 Running with Docker Compose

🌐 Service Access

📦 Installation

🚀 Running the Application

🧪 Testing

🔐 API Endpoints

Authentication

Profile Management (Protected)

Health & Monitoring

Example Usage

Traditional Registration & Login

Google OAuth Login

Web OAuth Flow

Mobile OAuth Flow

Apple Sign In

Protected Routes

🛠️ Built With

Core Framework

Architecture & Patterns

Authentication & Security

Database & Storage

Monitoring & Health

Testing

Development Tools

🏛️ Domain-Driven Design

Bounded Contexts

Aggregates

Domain Events

Sagas

📈 Monitoring & Observability

Structured Logging

Health Checks

Metrics (Prometheus)

Dashboards (Grafana)

⚙️ Configuration

🔒 Security Features

Authentication Security

Data Protection

Access Control

👨‍💻 Authors

📄 License

🙏 Acknowledgments

📚 Further Reading

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages