Building Scalable NestJS Applications with Clean Architecture

As applications grow in complexity, maintaining clean, testable, and scalable code becomes increasingly challenging. This is where Clean Architecture principles shine, especially when combined with the powerful NestJS framework. In this post, I'll walk you through implementing Clean Architecture in NestJS and explain why this approach has transformed how I build backend applications.

What is Clean Architecture?

Clean Architecture, introduced by Robert C. Martin (Uncle Bob), is a software design philosophy that organizes code into concentric layers, each with distinct responsibilities. The core principle is simple yet powerful: dependencies should always point inward, toward the business logic, never outward toward external concerns like databases or frameworks.

The Four Layers

1. Entities - Core business objects and rules
2. Use Cases - Application-specific business logic
3. Interface Adapters - Controllers, presenters, and gateways
4. Frameworks & Drivers - External tools like databases, web frameworks, and APIs

Why NestJS is Perfect for Clean Architecture

NestJS brings several advantages that make implementing Clean Architecture natural:

• Dependency Injection: Built-in IoC container makes it easy to inject dependencies
• Modular Structure: Encourages separation of concerns through modules
• TypeScript First: Strong typing helps maintain clear boundaries between layers
• Decorator-based: Clean, declarative approach to defining components

Project Structure That Makes Sense

Here's how I organize my NestJS projects following Clean Architecture principles:

src/
├── domain/
│   ├── entities/
│   ├── repositories/
│   └── services/
├── application/
│   ├── use-cases/
│   ├── dto/
│   └── interfaces/
├── infrastructure/
│   ├── database/
│   ├── repositories/
│   ├── external-services/
│   └── config/
└── presentation/
    ├── controllers/
    ├── guards/
    └── interceptors/

Implementing the Domain Layer

The domain layer contains your business entities and core logic. Here's an example of a clean domain entity:

// domain/entities/user.entity.ts
export class User {
  constructor(
    public readonly id: string,
    public readonly email: string,
    public readonly name: string,
    private _isActive: boolean = true
  ) {}

  public activate(): void {
    this._isActive = true;
  }

  public deactivate(): void {
    this._isActive = false;
  }

  public get isActive(): boolean {
    return this._isActive;
  }
}

Use Cases: The Heart of Your Application

Use cases encapsulate your application's business logic. They're independent of frameworks and external dependencies:

// application/use-cases/create-user.use-case.ts
export class CreateUserUseCase {
  constructor(
    private readonly userRepository: UserRepository,
    private readonly emailService: EmailService
  ) {}

  async execute(userData: CreateUserDto): Promise<User> {
    const user = new User(generateId(), userData.email, userData.name);

    await this.userRepository.save(user);
    await this.emailService.sendWelcomeEmail(user.email);

    return user;
  }
}

Repository Pattern for Data Access

Abstract your data access behind interfaces to keep your business logic database-agnostic:

// domain/repositories/user.repository.ts
export interface UserRepository {
  save(user: User): Promise<void>;
  findById(id: string): Promise<User | null>;
  findByEmail(email: string): Promise<User | null>;
}

// infrastructure/repositories/typeorm-user.repository.ts
@Injectable()
export class TypeormUserRepository implements UserRepository {
  constructor(
    @InjectRepository(UserEntity)
    private readonly userRepo: Repository<UserEntity>
  ) {}

  async save(user: User): Promise<void> {
    const userEntity = this.toEntity(user);
    await this.userRepo.save(userEntity);
  }

  // ... other methods
}

Controllers: Thin and Focused

Controllers should be thin layers that handle HTTP concerns and delegate to use cases:

// presentation/controllers/user.controller.ts
@Controller("users")
export class UserController {
  constructor(
    private readonly createUserUseCase: CreateUserUseCase,
    private readonly getUserUseCase: GetUserUseCase
  ) {}

  @Post()
  async create(@Body() createUserDto: CreateUserDto): Promise<UserResponse> {
    const user = await this.createUserUseCase.execute(createUserDto);
    return new UserResponse(user);
  }

  @Get(":id")
  async findOne(@Param("id") id: string): Promise<UserResponse> {
    const user = await this.getUserUseCase.execute(id);
    return new UserResponse(user);
  }
}

Dependency Injection Made Simple

Wire everything together using NestJS modules:

// infrastructure/infrastructure.module.ts
@Module({
  imports: [TypeOrmModule.forFeature([UserEntity])],
  providers: [
    {
      provide: "UserRepository",
      useClass: TypeormUserRepository,
    },
    {
      provide: "EmailService",
      useClass: SendgridEmailService,
    },
  ],
  exports: ["UserRepository", "EmailService"],
})
export class InfrastructureModule {}

// application/application.module.ts
@Module({
  imports: [InfrastructureModule],
  providers: [CreateUserUseCase, GetUserUseCase],
  exports: [CreateUserUseCase, GetUserUseCase],
})
export class ApplicationModule {}

Benefits I've Experienced

1. Testability

Each layer can be tested in isolation. Use cases can be unit tested without touching the database, and repositories can be mocked easily.

2. Flexibility

Want to switch from PostgreSQL to MongoDB? Just implement a new repository. Need to change email providers? Swap out the email service implementation.

3. Team Collaboration

Clear boundaries make it easier for teams to work on different parts of the application without stepping on each other's toes.

4. Maintainability

Business logic is centralized and doesn't leak into controllers or database layers, making it easier to understand and modify.

Common Pitfalls to Avoid

1. Don't over-abstract - Not every simple CRUD operation needs a complex use case
2. Keep entities pure - Avoid framework dependencies in your domain entities
3. Don't skip interfaces - Always define interfaces for external dependencies
4. Test boundaries - Ensure your layers don't have unexpected dependencies

When to Use Clean Architecture

Clean Architecture shines in:

• Complex business domains with intricate rules
• Long-lived applications that need to evolve
• Team environments where clear boundaries help collaboration
• Applications with multiple interfaces (REST API, GraphQL, CLI, etc.)

For simple CRUD applications, the overhead might not be worth it. But as your application grows, having this foundation pays dividends.

Conclusion

Clean Architecture in NestJS isn't just about following patterns—it's about building applications that can adapt to changing requirements while maintaining code quality. The initial setup might seem complex, but the long-term benefits of maintainable, testable, and flexible code make it worthwhile.

The key is to start simple and evolve your architecture as your application grows. Don't try to implement every pattern from day one, but keep the principles in mind as you build.

What's your experience with Clean Architecture in NestJS? Have you found different approaches that work well for your projects? I'd love to hear your thoughts in the comments below.