Clean Architecture

Clean Architecture

Separate stable business rules from volatile technical details.

Clean Architecture, formalized by Robert C. Martin (Uncle Bob) in Clean Architecture: A Craftsman's Guide to Software Structure and Design (2017), is an evolution of Layered Architecture, Hexagonal Architecture (Alistair Cockburn, 2005), and Onion Architecture (Jeffrey Palermo). It provides a set of principles for organizing code so that business logic remains independent of frameworks, UI, and databases.

"The goal of software architecture is to minimize the human resources required to build and maintain the required system." — Robert C. Martin

1. The Dependency Rule

Source code dependencies must always point inward, toward higher-level policies, never outward toward lower-level details.

┌─────────────────────────────────────────────────────────────┐
│                    OUTER LAYERS (Details)                    │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Frameworks & Drivers                                │   │
│  │  (React, FastAPI, gRPC, PostgreSQL, Redis, AWS)     │   │
│  │  ▲                                                  │   │
│  │  │ depends on                                       │   │
│  │  ▼                                                  │   │
│  │  Interface Adapters                                  │   │
│  │  (Controllers, Presenters, Gateways, Repositories)  │   │
│  │  ▲                                                  │   │
│  │  │ depends on                                       │   │
│  │  ▼                                                  │   │
│  │  Application Business Rules                          │   │
│  │  (Use Cases, Interactors, Application Services)     │   │
│  │  ▲                                                  │   │
│  │  │ depends on                                       │   │
│  │  ▼                                                  │   │
│  │  Enterprise Business Rules                           │   │
│  │  (Entities, Domain Objects, Value Objects)          │   │
│  └─────────────────────────────────────────────────────┘   │
│                    INNER LAYERS (Policies)                   │
└─────────────────────────────────────────────────────────────┘

Key implication: The inner circles (Entities, Use Cases) know nothing about the outer circles. They don't import framework libraries, don't know about the database, don't depend on the HTTP layer.

2. The Four Layers

Layer 1: Entities (Enterprise Business Rules)

What: Core business objects that encapsulate the most general and high-level rules.

Characteristics:

• Independent of the application — could be shared across multiple apps in the same domain
• Contain business logic that would exist even without this specific application
• Plain objects, no framework dependencies

// entity/Order.ts — pure business logic, no framework imports
export class Order {
  private constructor(
    private readonly id: string,
    private items: OrderItem[],
    private status: OrderStatus
  ) {}

  static create(items: OrderItem[]): Order {
    return new Order(crypto.randomUUID(), items, OrderStatus.PENDING);
  }

  addItem(item: OrderItem): void {
    if (this.status !== OrderStatus.PENDING) {
      throw new DomainError('Cannot modify a submitted order');
    }
    this.items.push(item);
  }

  submit(): void {
    if (this.items.length === 0) {
      throw new DomainError('Cannot submit empty order');
    }
    this.status = OrderStatus.SUBMITTED;
  }

  getTotal(): Money {
    return this.items.reduce(
      (sum, item) => sum.add(item.price.multiply(item.quantity)),
      Money.zero()
    );
  }
}

Layer 2: Use Cases (Application Business Rules)

What: Application-specific business rules. Orchestrate the flow of data to and from entities.

Characteristics:

• One Use Case = one user story / one JTBD outcome
• Contains NO framework code
• Depends only on Entities and interfaces (ports) defined in the same layer

// usecase/SubmitOrder.ts
import { Order } from '../entity/Order';
import { OrderRepository } from './port/OrderRepository';
import { PaymentGateway } from './port/PaymentGateway';
import { NotificationService } from './port/NotificationService';

export interface SubmitOrderInput {
  orderId: string;
  paymentMethod: PaymentMethod;
}

export interface SubmitOrderOutput {
  success: boolean;
  transactionId?: string;
  error?: string;
}

export class SubmitOrderUseCase {
  constructor(
    private orderRepo: OrderRepository,
    private paymentGateway: PaymentGateway,
    private notifier: NotificationService
  ) {}

  async execute(input: SubmitOrderInput): Promise<SubmitOrderOutput> {
    const order = await this.orderRepo.findById(input.orderId);
    if (!order) {
      return { success: false, error: 'Order not found' };
    }

    order.submit();

    const payment = await this.paymentGateway.charge(
      order.getTotal(),
      input.paymentMethod
    );

    if (!payment.success) {
      return { success: false, error: payment.error };
    }

    await this.orderRepo.save(order);
    await this.notifier.sendOrderConfirmation(order);

    return { success: true, transactionId: payment.transactionId };
  }
}

Layer 3: Interface Adapters

What: Convert data from the format most convenient for Use Cases and Entities, to the format most convenient for external agencies (frameworks, UI, database).

Characteristics:

• Controllers handle HTTP requests
• Presenters format responses
• Repositories implement data access interfaces
• Gateways wrap external APIs

// adapter/controller/OrderController.ts
import { SubmitOrderUseCase } from '../../usecase/SubmitOrder';

export class OrderController {
  constructor(private submitOrder: SubmitOrderUseCase) {}

  async handleSubmit(req: HttpRequest): Promise<HttpResponse> {
    const result = await this.submitOrder.execute({
      orderId: req.body.orderId,
      paymentMethod: req.body.paymentMethod
    });

    if (!result.success) {
      return { status: 400, body: { error: result.error } };
    }

    return { status: 200, body: { transactionId: result.transactionId } };
  }
}

// adapter/repository/PostgresOrderRepository.ts
import { OrderRepository } from '../../usecase/port/OrderRepository';

export class PostgresOrderRepository implements OrderRepository {
  constructor(private db: Knex) {}

  async findById(id: string): Promise<Order | null> {
    const row = await this.db('orders').where({ id }).first();
    return row ? this.toEntity(row) : null;
  }

  async save(order: Order): Promise<void> {
    await this.db('orders')
      .insert(this.toRow(order))
      .onConflict('id')
      .merge();
  }

  private toEntity(row: OrderRow): Order { /* ... */ }
  private toRow(order: Order): OrderRow { /* ... */ }
}

Layer 4: Frameworks & Drivers

What: The outermost layer — frameworks, tools, and delivery mechanisms.

Characteristics:

• React, Vue, Next.js (UI)
• Fastify, Express, FastAPI (HTTP)
• PostgreSQL, MongoDB, Redis (Database)
• AWS, GCP, Azure (Infrastructure)
• This layer contains only glue code — wiring dependencies together

// main.ts — composition root, only place where framework imports exist
import fastify from 'fastify';
import knex from 'knex';
import { OrderController } from './adapter/controller/OrderController';
import { SubmitOrderUseCase } from './usecase/SubmitOrder';
import { PostgresOrderRepository } from './adapter/repository/PostgresOrderRepository';
import { StripePaymentGateway } from './adapter/gateway/StripePaymentGateway';
import { EmailNotificationService } from './adapter/service/EmailNotificationService';

const app = fastify();
const db = knex({ client: 'pg', connection: process.env.DATABASE_URL });

// Wire dependencies — this is the ONLY place outer layers connect
const orderRepo = new PostgresOrderRepository(db);
const paymentGateway = new StripePaymentGateway(process.env.STRIPE_KEY);
const notifier = new EmailNotificationService();
const submitOrder = new SubmitOrderUseCase(orderRepo, paymentGateway, notifier);
const orderController = new OrderController(submitOrder);

app.post('/orders/:id/submit', orderController.handleSubmit.bind(orderController));

3. Ports and Adapters (Hexagonal Architecture)

Clean Architecture is conceptually equivalent to Hexagonal Architecture (Alistair Cockburn). The terminology differs:

                    ┌─────────────────┐
                    │   HTTP Client   │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  HTTP Adapter   │ ←── Driver Adapter
                    │  (Controller)   │
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │              ┌─────▼─────┐              │
        │              │           │              │
        │   ┌──────────┤  Port     ├──────────┐   │
        │   │          │ (interface)│          │   │
        │   │          └───────────┘          │   │
        │   │                                 │   │
        │   │    ┌───────────────────────┐    │   │
        │   │    │    APPLICATION        │    │   │
        │   │    │  ┌─────────────────┐  │    │   │
        │   │    │  │   Use Cases     │  │    │   │
        │   │    │  └─────────────────┘  │    │   │
        │   │    │  ┌─────────────────┐  │    │   │
        │   │    │  │    Entities     │  │    │   │
        │   │    │  └─────────────────┘  │    │   │
        │   │    └───────────────────────┘    │   │
        │   │                                 │   │
        │   │          ┌───────────┐          │   │
        │   │          │   Port    │          │   │
        │   │          │(interface)│          │   │
        │   │          └─────┬─────┘          │   │
        │   │                │                │   │
        │   └────────────────┼────────────────┘   │
        │                    │                    │
        │           ┌────────▼────────┐           │
        │           │  DB Adapter     │ ←── Driven Adapter
        │           │ (Repository)    │
        │           └────────┬────────┘           │
        │                    │                    │
        │           ┌────────▼────────┐           │
        │           │   PostgreSQL    │           │
        │           └─────────────────┘           │
        └─────────────────────────────────────────┘

Key rule: The application defines ports (interfaces). Adapters implement them. The application never knows which adapter is plugged in.

4. Boundaries and Crossing Them

The Boundary Crossing Rule

Data structures crossing boundaries must be simple, serializable DTOs — never framework-specific types.

// ❌ BAD: Framework type leaks into Use Case
class SubmitOrderUseCase {
  async execute(req: FastifyRequest): Promise<FastifyReply> { // ❌
    // ...
  }
}

// ✅ GOOD: Plain DTO in, plain DTO out
interface SubmitOrderInput {
  orderId: string;
  paymentMethod: PaymentMethod;
}

interface SubmitOrderOutput {
  success: boolean;
  transactionId?: string;
}

class SubmitOrderUseCase {
  async execute(input: SubmitOrderInput): Promise<SubmitOrderOutput> {
    // ... pure business logic
  }
}

Boundary Types

5. Package by Component (Simon Brown)

Simon Brown, creator of C4 Model, contributed "The Missing Chapter" to Uncle Bob's Clean Architecture book. His key insight:

Organize code by component, not by layer.

Package by Layer (Anti-pattern)

src/
  controllers/     ← All controllers
  services/        ← All services
  repositories/    ← All repositories
  models/          ← All entities

Problem: Business logic scattered across layers. High coupling. Hard to find related code.

Package by Feature (Better)

src/
  order/
    controller.ts
    service.ts
    repository.ts
    model.ts
  user/
    controller.ts
    service.ts
    repository.ts
    model.ts

Problem: Still no encapsulation — user/service.ts can import order/model.ts directly.

Package by Component (Recommended)

src/
  order/
    index.ts              ← Public API: OrderService, Order, OrderRepository
    internal/
      OrderEntity.ts      ← Entities (private)
      SubmitOrder.ts      ← Use Case (private)
      OrderController.ts  ← Adapter (private)
      PostgresOrderRepo.ts ← Adapter (private)
  user/
    index.ts              ← Public API: UserService, User, UserRepository
    internal/
      ...

Benefits:

• Each component is self-contained
• Public API surface is small and intentional
• Internal structure can change without affecting other components
• Maps directly to C4 L3 Components

6. Clean Architecture + C4 Model Integration

Workflow:

1. C4 L1 → Define system scope and external dependencies
2. C4 L2 → Identify containers (deployable units)
3. Clean Architecture → Design component boundaries within each container
4. C4 L3 → Draw components as self-contained packages
5. Clean Architecture → Implement: Entities → Use Cases → Adapters
6. C4 L4 → Document complex Entities with UML class diagrams

7. Clean Architecture + DDD Integration

Key difference:

• DDD focuses on discovering the domain model (Event Storming, Ubiquitous Language)
• Clean Architecture focuses on structuring the code to protect that model from technical details

Best practice: Use DDD to discover the model, then use Clean Architecture to implement it.

8. Testing Strategy

Clean Architecture enables a testing pyramid without integration tests for every case:

         ┌─────────┐
         │   E2E   │  ← 1-2 tests: happy path through HTTP + DB
         │  (slow) │
         └────┬────┘
              │
         ┌────▼────┐
         │ Adapter │  ← Mock the port, test adapter logic
         │  Tests  │
         └────┬────┘
              │
         ┌────▼────┐
         │  Use    │  ← Mock repositories, test business flow
         │  Case   │
         │  Tests  │
         └────┬────┘
              │
         ┌────▼────┐
         │ Entity  │  ← Pure unit tests, no mocks needed
         │  Tests  │     Fastest, most comprehensive
         └─────────┘

// Entity test — pure, fast, no mocks
import { Order } from './Order';

describe('Order', () => {
  it('cannot submit empty order', () => {
    const order = Order.create([]);
    expect(() => order.submit()).toThrow('Cannot submit empty order');
  });

  it('calculates total correctly', () => {
    const order = Order.create([
      { productId: '1', price: Money.of(10), quantity: 2 },
      { productId: '2', price: Money.of(5), quantity: 3 }
    ]);
    expect(order.getTotal()).toEqual(Money.of(35));
  });
});

// Use Case test — mock ports, test orchestration
import { SubmitOrderUseCase } from './SubmitOrder';

describe('SubmitOrderUseCase', () => {
  it('charges payment and confirms order', async () => {
    const orderRepo = { findById: vi.fn(), save: vi.fn() };
    const paymentGateway = { charge: vi.fn() };
    const notifier = { sendOrderConfirmation: vi.fn() };

    const useCase = new SubmitOrderUseCase(orderRepo, paymentGateway, notifier);
    const result = await useCase.execute({ orderId: '123', paymentMethod: 'card' });

    expect(result.success).toBe(true);
    expect(paymentGateway.charge).toHaveBeenCalled();
    expect(notifier.sendOrderConfirmation).toHaveBeenCalled();
  });
});

9. Anti-Patterns

10. Decision Framework

When to use Clean Architecture:

Complex business logic? ──→ YES ──→ Use Clean Architecture
    │
    └──→ NO ──→ Simple CRUD? ──→ YES ──→ Simple layered / MVC is fine
                  │
                  └──→ NO ──→ Prototype / MVP? ──→ YES ──→ Start simple,
                                                          refactor later

When Clean Architecture is overkill:

• Simple CRUD applications with no complex business rules
• Prototypes / throwaway code
• Scripts and CLI tools
• Simple static sites

Integration with Other Skills

References

• Clean Architecture — Robert C. Martin (2017)
• Hexagonal Architecture — Alistair Cockburn (2005)
• C4 Model — Simon Brown
• Package by Component — Simon Brown
• The Clean Code Blog — Robert C. Martin