clean-architecture

Clean Architecture

Overview

Clean Architecture separates code into concentric layers with the Dependency Rule: source code dependencies always point inward. Business logic never depends on frameworks, databases, or UI.

Layer Structure

src/
├── domain/                  # Innermost — entities + business rules
│   ├── entities/
│   │   └── User.ts
│   └── value-objects/
│       └── Email.ts
├── application/             # Use cases — orchestrate domain logic
│   ├── use-cases/
│   │   ├── CreateUser.ts
│   │   └── GetUserById.ts
│   └── ports/               # Interfaces (driven/driving)
│       ├── UserRepository.ts
│       └── EmailService.ts
├── infrastructure/          # Outermost — frameworks, DB, external APIs
│   ├── persistence/
│   │   └── PgUserRepository.ts
│   ├── services/
│   │   └── SendGridEmailService.ts
│   └── web/
│       ├── routes.ts
│       └── controllers/
│           └── UserController.ts
└── main.ts                  # Composition root — wires everything together

Core Patterns

Entity (Domain Layer)

// Pure business logic — no framework imports
export class User {
  constructor(
    public readonly id: string,
    public readonly email: Email,
    public name: string,
    private passwordHash: string,
  ) {}

  changeName(newName: string): void {
    if (newName.length < 2) throw new DomainError('Name too short');
    this.name = newName;
  }

  verifyPassword(plaintext: string): boolean {
    return hashCompare(plaintext, this.passwordHash);
  }
}

Use Case (Application Layer)

// Depends only on ports (interfaces), not implementations
export class CreateUser {
  constructor(
    private userRepo: UserRepository,
    private emailService: EmailService,
  ) {}

  async execute(input: { email: string; name: string; password: string }): Promise<User> {
    const existing = await this.userRepo.findByEmail(input.email);
    if (existing) throw new ConflictError('Email already registered');

    const user = User.create(input);
    await this.userRepo.save(user);
    await this.emailService.sendWelcome(user.email);
    return user;
  }
}