NestJS Customer CRUD API with CQRS & Clean Architecture

A NestJS CRUD API for customer management with CQRS and Clean Architecture. Features PostgreSQL, Prisma ORM, input validation (phone/email/IBAN), Docker support, Swagger docs, and Jest tests. Follows DDD principles for scalable backend development.

Key Features

• CQRS Architecture: Clear separation of commands and queries
• Domain-Driven Design: Focused business logic implementation
• Comprehensive Validation:
  • Phone number validation using Google LibPhoneNumber
  • Email and IBAN validation
  • Unique customer constraints
• Production-ready Infrastructure:
  • Health checks via Terminus (/health endpoint)
  • API documentation with Swagger
  • Consistent response formatting via ResponseInterceptor
  • Global exception handling with HttpExceptionFilter

Getting Started

Prerequisites

• Docker
• Docker Compose

Setup Instructions

1. Setup ‍‍‍.env

   cp .env.example .env

2. Run the application

   docker-compose up --build

3. Run tests

   docker-compose -f docker-compose.test.yml up --build

4. Access Swagger UI

   http://localhost:3000/api

The project structure

.
├── customer-service
│ ├── dist
│ ├── package.json
│ ├── prisma
│ │ ├── migrations
│ │ └── schema.prisma
│ ├── test
│ │ ├── mocks
│ │ └── setup
│ └── src
│ ├── main.ts
│ ├── app.module.ts
│ ├── common
│ │ ├── exceptions
│ │ ├── filters
│ │ ├── interceptors
│ │ ├── logger
│ │ ├── utils
│ │ └── validations
│ ├── domain
│ │ └── customer
│ │ └── events
│ ├── application
│ │ ├── command
│ │ ├── handlers
│ │ ├── queries
│ │ └── services
│ ├── interface
│ │ ├── controllers
│ │ ├── docs
│ │ ├── dtos
│ │ └── pipes
│ └── infrastructure
│ ├── health
│ ├── prisma
│ └── repositories
├── docker-compose.yml
├── Dockerfile
└── README.md

Core Implementation

Validation Pipeline

• Phone number validation for mobile numbers only
• IBAN validation for bank accounts
• Email format validation
• Unique constraints enforcement
• Partial update validation (ensures at least one field is present via PipeTransform)

API Standards

• Global ResponseInterceptor for consistent API responses
• Custom exception formatting via HttpExceptionFilter
• Paginated response DTO with metadata
• Sensitive customer data masking in logs

Database Management

• Prisma ORM with PostgreSQL
• Schema location: customer-service/prisma/schema.prisma
• Automatic migrations on startup
• Isolated test database (created/destroyed during test runs)

Testing

• Jest test configuration
• Database setup/teardown hooks

Monitoring & Health Checks

• Terminus healthcheck available at /health endpoint
• Includes database connectivity check
• Custom health indicators can be added

Custom Components

• IAppLogger: Custom logger interface injected via NestJS DI
• Domain-specific events for customer operations