NestJS Architectural Patterns: Clean Architecture vs Controller-Service-Repository

Introduction

When building scalable and maintainable applications with NestJS, choosing the right architecture pattern is critical. NestJS, built on top of TypeScript and leveraging TypeScript's strong typing and Node.js's non-blocking I/O model, offers developers the flexibility to structure their code in various ways. Two popular architectural patterns that often come up in production-grade NestJS applications are Clean Architecture and the Controller-Service-Repository (CSR) pattern.

Clean Architecture emphasizes the separation of concerns, pushing business logic to the core of the application, while the Controller-Service-Repository pattern follows a more straightforward hierarchical structure where controllers handle HTTP requests, services contain application logic, and repositories manage data access. Understanding the nuances, trade-offs, and appropriate use cases for each pattern can dramatically improve code quality, testability, and long-term maintainability.

This article provides a deep dive into both patterns, comparing them across several dimensions, illustrating implementation details with production-ready code examples, and offering best practices, common pitfalls, performance considerations, and security insights. Whether you're starting a new NestJS project, refactoring an existing codebase, or simply want to broaden your architectural knowledge, this guide equips you with the knowledge to make an informed decision and apply the chosen pattern effectively.

Table of Contents

• Introduction
• Core Concepts
• Architecture Overview
• Step-by-Step Guide
• Real-World Examples
• Production Code Examples
• Comparison Table
• Best Practices
• Common Mistakes
• Performance Tips
• Security Considerations
• Deployment Notes
• Debugging Tips
• FAQ
• Conclusion

Core Concepts

Before diving into the specifics of Clean Architecture and Controller-Service-Repository, it's essential to understand the underlying concepts they are built upon.

What is Clean Architecture?

Clean Architecture, introduced by Robert C. Martin (Uncle Bob), is an architectural pattern that promotes the separation of concerns by isolating business logic from external concerns like databases, user interfaces, and frameworks. The core idea is to have a set of concentric circles (or layers) where the innermost circle contains the business rules (use cases), and each outward layer deals with more peripheral concerns such as interface adapters (controllers, presentation), frameworks, and external services.

In NestJS, Clean Architecture typically translates to having separate modules for domain logic (often called domain or core modules), use case services, data mappers, and adapters that bridge the domain with Nest's controllers and services.

What is Controller-Service-Repository?

The Controller-Service-Repository pattern is a straightforward, three-tier architecture commonly used in web applications. It comprises:

• Controller: Handles HTTP requests, validates input, and delegates processing to services.
• Service: Contains the application logic, orchestrates operations, and often interacts with repositories.
• Repository: Encapsulates data access logic, providing an abstraction over the underlying database or external data sources.

This pattern aligns well with NestJS's philosophy of providing ready-made structures for controllers (Nest controllers) and services (Nest services) via decorators like @Controller, @Injectable, and dependency injection.

Key Differences

While both patterns aim to produce organized, testable code, they differ in:

• Complexity: Clean Architecture introduces more layers and stricter separation, making it more complex but also more flexible.
• Focus: Clean Architecture emphasizes business rules isolation; CSR focuses on request handling flow.
• Flexibility: CSR is more rigid but easier to adopt for small to medium projects; Clean Architecture allows easier swapping of UI, database, and external services.
• Testability: Clean Architecture enables unit testing of business logic independent of any framework; CSR tests are often integration-style tests covering the whole flow.

When to Choose Which

Choosing between them depends on project size, team experience, future scalability needs, and maintainability expectations. Larger enterprises with complex domain logic often benefit from Clean Architecture. Simpler projects with straightforward requirements may adopt CSR to reduce overhead.

Architecture Overview

In this section, we illustrate how each pattern manifests in NestJS code.

Clean Architecture Overview

A Clean Architecture NestJS project structure might look like this:

src/├── domain/ (core business rules)│   ├── entities/ (User, Product, Order)│   ├── repositories/ (UserRepository, ProductRepository)│   └── use-cases/ (CreateUserUseCase, UpdateProductUseCase)├── application/ (application services, DTOs)│   ├── dto/ (create-user.dto.ts)│   ├── services/ (UserService, ProductService)│   └── ports/ (OutputPort, InputPort)├── infrastructure/ (adapters, frameworks)│   ├── controllers/ (Nest controllers)│   ├── services/ (external APIs, email services)│   ├── database/ (typeorm, mongoose adapters)│   └── modules/ (Nest modules that bridge)└── main.ts (bootstrap)

Key points:

• Domain (inner) depends only on idiomatic TypeScript, no frameworks.
• Application layer defines use cases and orchestrates domain and infrastructure.
• Infrastructure layer includes Nest-specific adapters (controllers, repositories) that depend only on the application layer.
• Each layer can be tested independently.

Controller-Service-Repository Overview

src/├── controllers/ (Nest controllers)│   ├── user.controller.ts│   ├── product.controller.ts│   └── order.controller.ts├── services/ (application logic)│   ├── user.service.ts│   ├── product.service.ts│   └── order.service.ts├── repositories/ (data access)│   ├── user.repository.ts│   ├── product.repository.ts│   └── order.repository.ts└── main.ts (bootstrap)

Here, the controller directly uses a service, which in turn uses a repository. Dependency injection is leveraged via Nest's decorator system.

Step-by-Step Guide

Let's walk through implementing both patterns from scratch, using a simple user management feature as an example.

Setting Up the Project

First, create a new NestJS project (using npx @nestjs/cli new nest-arch-demo). Then, navigate into the project directory.

Pattern 1: Controller-Service-Repository Implementation

1. Create a User entity: src/entities/user.entity.ts
2. Create a UserRepository interface and implementation: src/repositories/user.repository.ts
3. Create a UserService: src/services/user.service.ts
4. Create a UserController: src/controllers/user.controller.ts

Here's a quick snippet of each:

User Entity

// src/entities/user.entity.tsexport class User {  id: string;  name: string;  email: string;  createdAt: Date;}

UserRepository

// src/repositories/user.repository.tsimport { User } from '../entities/user.entity';export interface IUserRepository {  findAll(): Promise;  findById(id: string): Promise;  create(user: User): Promise;  update(id: string, user: Partial): Promise;  delete(id: string): Promise;}export class UserRepository implements IUserRepository {  private users: User[] = [];  async findAll(): Promise {    return this.users;  }  async findById(id: string): Promise {    return this.users.find(u => u.id === id);  }  async create(user: User): Promise<User> {    this.users.push(user);    return user;  }  async update(id: string, user: Partial<User>): Promise<User> {    const index = this.users.findIndex(u => u.id === id);    if (index === -1) throw new Error('User not found');    this.users[index] = { ...this.users[index], ...user };    return this.users[index];  }  async delete(id: string): Promise<void> {    const index = this.users.findIndex(u => u.id === id);    if (index !== -1) this.users.splice(index, 1);  }}

UserService

// src/services/user.service.tsimport { Inject } from '@nestjs/common';import { IUserRepository } from '../repositories/user.repository';import { User } from '../entities/user.entity';export class UserService {  constructor(@Inject('IUserRepository') private repo: IUserRepository) {}  async getUsers() {    return this.repo.findAll();  }  async getUser(id: string) {    return this.repo.findById(id);  }  async addUser(userData: Omit<User, 'id' | 'createdAt'>) {    const user: User = {      id: Math.random().toString(),      createdAt: new Date(),      ...userData,    };    return this.repo.create(user);  }}

UserController

// src/controllers/user.controller.tsimport { Controller, Get, Post, Body, Param } from '@nestjs/common';import { UserService } from '../services/user.service';import { User } from '../entities/user.entity';@Controller('users')export class UserController {  constructor(private readonly userService: UserService) {}  @Get()  async findAll() {    return this.userService.getUsers();  }  @Get(':id')  async findOne(@Param('id') id: string) {    return this.userService.getUser(id);  }  @Post()  async create(@Body() userData: Omit<User, 'id' | 'createdAt'>) {    return this.userService.addUser(userData);  }}

Pattern 2: Clean Architecture Implementation

Clean Architecture introduces more layers. Let's map the same user feature across Clean Architecture layers.

Domain Layer (Core)

Define entities, repositories, and use cases without any Nest-specific code.

User Entity

// src/domain/entities/user.entity.tsexport class User {  id: string;  name: string;  email: string;  createdAt: Date;}

UserRepository Interface (Port)

// src/domain/repositories/user-repository.port.tsimport { User } from '../entities/user.entity';export interface UserRepositoryPort {  findAll(): Promise<User[]>;  findById(id: string): Promise<User>;  save(user: User): Promise<User>;  update(id: string, user: Partial<User>): Promise<User>;  delete(id: string): Promise<void>;}

Use Cases

// src/domain/use-cases/create-user.use-case.tsimport { User } from '../entities/user.entity';import { UserRepositoryPort } from '../repositories/user-repository.port';export class CreateUserUseCase {  constructor(private repo: UserRepositoryPort) {}  async execute(name: string, email: string): Promise<User> {    const user = new User();    user.id = Math.random().toString();    user.name = name;    user.email = email;    user.createdAt = new Date();    return this.repo.save(user);  }}

Application Layer

Application services orchestrate use cases, define DTOs, and may contain validation.

UserApplicationService

// src/application/services/user-application.service.tsimport { Injectable } from '@nestjs/common';import { CreateUserUseCase } from '../../domain/use-cases/create-user.use-case';import { User } from '../../domain/entities/user.entity';@Injectable()export class UserApplicationService {  constructor(    private createUserUseCase: CreateUserUseCase,    private findUserUseCase: FindUserUseCase,  ) {}  async createUser(name: string, email: string) {    return this.createUserUseCase.execute(name, email);  }  async getUser(id: string) {    return this.findUserUseCase.execute(id);  }}

Infrastructure Layer (Adapters)

Implement repositories using TypeORM or a simple in-memory store, and Nest controllers that expose HTTP endpoints.

UserRepository Adapter

// src/infrastructure/adapters/user-in-memory.repository.adapter.tsimport { UserRepositoryPort } from '../../domain/repositories/user-repository.port';import { User } from '../../domain/entities/user.entity';export class UserInMemoryRepositoryAdapter implements UserRepositoryPort {  private store: User[] = [];  async findAll(): Promise<User[]> {    return this.store;  }  async findById(id: string): Promise<User> {    return this.store.find(u => u.id === id);  }  async save(user: User): Promise<User> {    this.store.push(user);    return user;  }  async update(id: string, user: Partial<User>): Promise<User> {    const index = this.store.findIndex(u => u.id === id);    if (index === -1) throw new Error('User not found');    this.store[index] = { ...this.store[index], ...user };    return this.store[index];  }  async delete(id: string): Promise<void> {    const index = this.store.findIndex(u => u.id === id);    if (index !== -1) this.store.splice(index, 1);  }}

UserController (Adapter)

// src/infrastructure/controllers/user.controller.tsimport { Controller, Get, Post, Body, Param } from '@nestjs/common';import { UserApplicationService } from '../services/user-application.service';@Controller('users')export class UserController {  constructor(private appService: UserApplicationService) {}  @Get()  async findAll() {    // The application service might expose a findAll method    // For brevity, assume we have a FindAllUsersUseCase injected.    return { message: 'List users' };  }  @Get(':id')  async findOne(@Param('id') id: string) {    return this.appService.getUser(id);  }  @Post()  async create(@Body() body: any) {    const { name, email } = body;    return this.appService.createUser(name, email);  }}

Wiring Everything Together (NestJS Module)

Create a module that ties the adapters and services using Nest's dependency injection.

// src/infrastructure/infrastructure.module.tsimport { Module } from '@nestjs/common';import { UserController } from './controllers/user.controller';import { UserApplicationService } from './services/user-application.service';import { UserInMemoryRepositoryAdapter } from './adapters/user-in-memory.repository.adapter';import { CreateUserUseCase } from '../../domain/use-cases/create-user.use-case';import { FindUserUseCase } from '../../domain/use-cases/find-user.use-case';@Module({  controllers: [UserController],  providers: [    UserApplicationService,    {      provide: 'UserRepositoryPort',      useClass: UserInMemoryRepositoryAdapter,    },    CreateUserUseCase,    FindUserUseCase,  ],})export class InfrastructureModule {}

Module Integration

Import InfrastructureModule into the main AppModule to bootstrap the application.

// src/app.module.tsimport { Module } from '@nestjs/common';import { InfrastructureModule } from './infrastructure/infrastructure.module';@Module({  imports: [InfrastructureModule],})export class AppModule {}

Running the Application

Run npm run start:dev and test endpoints with a tool like Postman or curl. You should be able to perform CRUD operations on users using both patterns.

Real-World Examples

Many production NestJS applications adopt Clean Architecture for its flexibility, especially when dealing with multiple external services (e.g., payment gateways, email services). Companies like SoundCloud, Deliveroo, and Airbnb have open-sourced their NestJS architecture patterns, often heavily leaning on Clean Architecture principles.

On the other hand, many smaller SaaS products and internal tools adopt the CSR pattern for its simplicity and faster time-to-market. For instance, a typical blog API may implement a simple CSR pattern: controller → service → repository (using TypeORM). The codebase remains maintainable and easy to onboard new developers.

Example 1: Clean Architecture in a Microservice

Consider a NestJS microservice that processes payments. The Clean Architecture approach would separate the payment domain (entities like Payment, Transaction), use cases (ProcessPayment, RefundPayment), adapters for Kafka, gRPC, and HTTP gateways, and an infrastructure layer containing the Kafka consumer, gRPC server, and REST controller. This ensures that the core payment logic remains independent of transport mechanisms.

Example 2: CSR in a Simple CRUD API

A simple CRUD API for a todo list can be built with CSR: TodoController handles HTTP verbs, TodoService orchestrates business logic (like marking all as completed), and TodoRepository uses TypeORM to persist data. This pattern is intuitive and quick to prototype.

Production Code Examples

Below are production-ready code blocks for each pattern, with comments and best practices.

CSR Pattern: User Management with TypeORM

// src/user.entity.tsimport { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn } from 'typeorm';@Entity()export class User {  @PrimaryGeneratedColumn('uuid')  id: string;  @Column()  name: string;  @Column({ unique: true })  email: string;  @CreateDateColumn()  createdAt: Date;}// src/user.repository.tsimport { Injectable } from '@nestjs/common';import { InjectRepository } from '@nestjs/typeorm';import { Repository } from 'typeorm';import { User } from './user.entity';@Injectable()export class UserRepository {  constructor(    @InjectRepository(User)    private repo: Repository<User>,  ) {}  async findAll(): Promise<User[]> {    return this.repo.find();  }  async findById(id: string): Promise<User> {    return this.repo.findOneBy({ id });  }  async create(user: User): Promise<User> {    return this.repo.save(user);  }  async update(id: string, updates: Partial<User>): Promise<User> {    await this.repo.update(id, updates);    return this.repo.findOneBy({ id });  }  async delete(id: string): Promise<void> {    await this.repo.delete(id);  }}// src/user.service.tsimport { Inject, Injectable } from '@nestjs/common';import { UserRepository } from './user.repository';import { User } from './user.entity';@Injectable()export class UserService {  constructor(@Inject() private userRepo: UserRepository) {}  async getUsers() {    return this.userRepo.findAll();  }  async getUser(id: string) {    return this.userRepo.findById(id);  }  async addUser(dto: { name: string; email: string }) {    const user = this.userRepo.create({ ...dto, id: undefined, createdAt: new Date() });    return this.userRepo.save(user);  }}// src/user.controller.tsimport { Controller, Get, Post, Body, Param } from '@nestjs/common';import { UserService } from './user.service';import { User } from './user.entity';@Controller('users')export class UserController {  constructor(private readonly userService: UserService) {}  @Get()  async findAll() {    return this.userService.getUsers();  }  @Get(':id')  async findOne(@Param('id') id: string) {    return this.userService.getUser(id);  }  @Post()  async create(@Body() dto: { name: string; email: string }) {    return this.userService.addUser(dto);  }}

Clean Architecture Pattern: Payment Processing with Use Cases

// domain/entities/payment.entity.tsexport class Payment {  id: string;  amount: number;  currency: string;  status: 'pending' | 'completed' | 'failed';  createdAt: Date;}// domain/ports/payment-gateway.port.tsexport interface PaymentGatewayPort {  charge(amount: number, currency: string): Promise<{ id: string; status: string }>;  refund(id: string): Promise<{ id: string; status: string }>;}// domain/use-cases/process-payment.use-case.tsimport { Payment } from '../entities/payment.entity';import { PaymentGatewayPort } from '../ports/payment-gateway.port';import { PaymentRepositoryPort } from '../ports/payment-repository.port';export class ProcessPaymentUseCase {  constructor(    private gateway: PaymentGatewayPort,    private repo: PaymentRepositoryPort,  ) {}  async execute(amount: number, currency: string): Promise<Payment> {    // 1. Charge the gateway    const chargeResult = await this.gateway.charge(amount, currency);    // 2. Create payment entity    const payment = new Payment();    payment.id = chargeResult.id;    payment.amount = amount;    payment.currency = currency;    payment.status = chargeResult.status as any;    payment.createdAt = new Date();    // 3. Persist    return this.repo.save(payment);  }}// infrastructure/adapters/stripe-adapter.tsimport { PaymentGatewayPort } from '../../domain/ports/payment-gateway.port';import Stripe from 'stripe';export class StripeAdapter implements PaymentGatewayPort {  private stripe: Stripe;  constructor() {    this.stripe = new Stripe(process.env.STRIPE_SECRET_KEY);  }  async charge(amount: number, currency: string): Promise<{ id: string; status: string }> {    const charge = await this.stripe.charges.create({      amount: amount * 100, // in cents      currency,      source: 'tok_visa', // example token    });    return { id: charge.id, status: charge.status };  }  async refund(id: string): Promise<{ id: string; status: string }> {    const refund = await this.stripe.refunds.create({ charge: id });    return { id: refund.id, status: refund.status };  }}// infrastructure/controllers/payment.controller.tsimport { Controller, Post, Body } from '@nestjs/common';import { ProcessPaymentUseCase } from '../../domain/use-cases/process-payment.use-case';@Controller('payments')export class PaymentController {  constructor(private processPaymentUseCase: ProcessPaymentUseCase) {}  @Post('charge')  async charge(@Body() body: { amount: number; currency: string }) {    return this.processPaymentUseCase.execute(body.amount, body.currency);  }}

Comparison Table

Best Practices

For Clean Architecture in NestJS

• Keep the domain layer free from external dependencies (no Nest, TypeORM, etc.). Use interfaces only.
• Follow the Dependency Inversion Principle: high-level modules should not depend on low-level modules; both should depend on abstractions.
• Use Nest's built-in dependency injection but carefully map adapters to ports.
• Separate DTOs (Data Transfer Objects) from entities; define validation schemas (e.g., using class-validator) in the application layer.
• Implement a dedicated error handling strategy for each layer (domain errors vs. adapter errors).

For CSR Pattern

• Make services thin wrappers around repositories; keep business logic at service level.
• Use Nest's built-in validation (class-validator + class-transformer) for input validation.
• Apply proper logging and monitoring across layers.
• Ensure repository implementations are tested with real database or mock providers.

Common Mistakes

Clean Architecture Pitfalls

• Mix framework code into domain entities (e.g., adding Nest decorators to domain classes). This defeats the purpose of separation.
• Over-engineering: using too many layers for trivial applications, leading to unnecessary boilerplate.
• Neglecting the outer layers' responsibility: forgetting to implement adapters for HTTP, message queues, etc.

CSR Pattern Pitfalls

• Controller containing business logic (e.g., complex calculations) – violates single responsibility.
• Service directly calling repository without abstraction (hard to mock).
• Missing input validation, leading to inconsistent data.

Performance Tips

Clean Architecture

• Use lazy loading for modules to reduce initial startup time.
• Implement caching at the repository or use-case level for read-heavy operations.
• Consider using event-driven architecture for decoupled services (e.g., publish/subscribe).

CSR Pattern

• Optimize database queries (e.g., eager loading, proper indexing).
• Employ connection pooling for the database (Nest's TypeORM configuration).
• Use pagination for list endpoints to avoid overwhelming the client.

Security Considerations

General Security Best Practices

• Always validate and sanitize input data, both in the controller and at the domain level.
• Use Nest's built-in CSRF protection for state-changing operations if needed.
• Implement proper authentication (JWT, OAuth2) and authorization (roles) at the controller level; consider moving authorization checks into domain use cases for stronger guarantees.
• Encrypt sensitive data at rest; use environment variables for secrets, never hardcode.
• Rate limit API endpoints using Nest's built-in guard or external libraries like Rate Limiter.

Pattern Specific Security Notes

• Clean Architecture isolates business logic, making it easier to enforce domain-level security rules (e.g., "users can only update their own profile") independent of the transport layer.
• In CSR, ensure that services don't inadvertently expose sensitive data; always apply the principle of least privilege when granting database access.

Deployment Notes

Clean Architecture

• Containerize the application using Docker; each adapter (e.g., HTTP gateway, gRPC server) could be separate containers if needed.
• Utilize Nest's built-in clustering for CPU-intensive tasks.
• Use environment-specific configurations for infrastructure adapters (database connections, external API keys).

CSR Pattern

• Deploy as a standard NestJS app; monitor request latency and ensure the database connection pool is tuned.
• Consider using a reverse proxy (Nginx) for SSL termination and load balancing.

Debugging Tips

• Enable structured logging (e.g., Winston) to trace request flow across layers.
• In Clean Architecture, ensure that each layer's responsibilities are clear; use breakpoints in domain code to verify business logic execution.
• In CSR, debugging is straightforward because the flow is linear: controller → service → repository.
• Use Nest's built-in DevTools extension for debugging in development.

FAQ

Q1: Can I mix Clean Architecture and CSR in the same NestJS project?

A: Yes, you can have multiple modules each following a different pattern, as long as you maintain clear boundaries and avoid coupling. However, consistency is usually recommended for maintainability.

Q2: Which pattern is easier for a team new to NestJS?

A: CSR is generally easier because it aligns with NestJS's default conventions and requires fewer layers to understand.

Q3: Does Clean Architecture require additional libraries or frameworks?

A: It doesn't strictly require extra libraries, but you may use Domain-Driven Design (DDD) tools, event sourcing libraries, or adapters for specific protocols. NestJS itself can serve as the adapter framework.

Q4: How do I test use cases in Clean Architecture?

A: Write unit tests for use cases by mocking ports (repositories, external gateways) and verifying business rule enforcement.

10: How do I handle validation errors in Clean Architecture?

A: Validate input in the application layer using libraries like class-validator, then raise domain-specific errors that can be caught by the adapter layer and transformed into appropriate HTTP responses.

Q5: Are there performance penalties for Clean Architecture?

A: The overhead is minimal; each extra layer adds a method call and possibly an extra abstraction lookup. For most applications, the performance impact is negligible compared to the benefits in maintainability and testability.

Q6: Can I use TypeORM with CSR pattern?

A: Absolutely. TypeORM integrates seamlessly with NestJS services and repositories.

Q7: How does authentication integrate with CSR pattern?

A: Implement authentication guards at the controller level, then pass authenticated user info (e.g., userId) to services. Services can then use repositories to enforce authorization rules.

Q8: What about error handling across layers?

A: Define custom error classes in the domain (e.g., BusinessLogicError) and map them to HTTP status codes in the adapter layer using Nest's exception filters.

Q9: Can I use GraphQL with Clean Architecture?

A: Yes, GraphQL can be one of the adapters, handling query/mutation resolution while the domain remains unchanged.

Q10: Which pattern is more suitable for microservices?

A: Clean Architecture is more suitable because it allows you to share domain logic across multiple services and easily swap communication protocols (gRPC, Kafka, REST) without altering business rules.

Conclusion

Choosing between Clean Architecture and the Controller-Service-Repository pattern for NestJS depends heavily on your project's complexity, team expertise, and future scaling expectations. Clean Architecture offers a robust, highly maintainable structure that isolates business logic from external concerns, making it ideal for enterprise-grade applications or systems that require multiple interfaces (REST, GraphQL, event streams). CSR, while simpler and more aligned with NestJS's default conventions, provides a pragmatic approach for small to medium projects where speed-to-market and ease of understanding are priorities.

By understanding the nuances, implementing best practices, and considering performance and security throughout, you can confidently adopt the pattern that best fits your context. Start with CSR if you need rapid prototyping and evolve towards Clean Architecture as your application grows and its domain complexity increases. Conversely, if you anticipate a complex domain from the outset, invest in Clean Architecture early to avoid technical debt.

Feel free to experiment with both patterns in side projects, compare their trade-offs, and refine your approach. The NestJS ecosystem continues to evolve, providing powerful tools to support both patterns. For further reading, refer to the official NestJS documentation, Uncle Bob's writings on Clean Architecture, and community best practices on platforms like GitHub and Stack Overflow.

Happy coding, and may your applications be scalable, secure, and maintainable!