Clean Architecture

Overview

Clean Architecture, popularized by Robert C. Martin, organizes code into concentric layers where dependencies point only inward. At the center are entities (core business rules), then use cases (application-specific rules), then interface adapters (controllers, presenters, repositories), and on the outside frameworks and drivers (web framework, database, external APIs).

The key idea is the dependency rule: business logic never depends on frameworks, databases, or UI. Outer layers implement interfaces defined by inner layers (dependency inversion). This makes the core testable without infrastructure and lets you swap databases or frameworks with limited impact. Hexagonal architecture (ports and adapters) and onion architecture express the same idea.

When to use it

• Applications with significant business logic that must outlive frameworks.
• Codebases where testability is a priority.
• Teams wanting clear conventions for where code belongs.
• Services that integrate with many external systems.

Where it shows up in interviews

Where it is used in real software

Key terms

Entities

Enterprise-wide business rules and objects.

Use cases / interactors

Application-specific operations orchestrating entities.

Ports

Interfaces the core defines (OrderRepository, PaymentGateway).

Adapters

Implementations of ports for specific technologies.

Dependency rule

Source code dependencies point only inward.

How it works, step by step

1. 1
   Model the domain

   Entities with business rules, no framework imports.

2. 2
   Write use cases

   PlaceOrder, RefundPayment, depending only on ports.

3. 3
   Define ports

   Interfaces for persistence, messaging, external services.

4. 4
   Implement adapters

   PostgresOrderRepository, StripePaymentGateway.

5. 5
   Wire at the edge

   Composition root injects adapters into use cases.

Layers and dependencies

Where code goes

You can test PlaceOrder with in-memory fakes, no database or HTTP server required.

Implementation

1// Domain (no imports from frameworks)2export class Order {3  constructor(readonly id: string, readonly items: { sku: string; qty: number; priceCents: number }[]) {4    if (items.length === 0) throw new Error("Order must have items");5  }6  total() { return this.items.reduce((s, i) => s + i.qty * i.priceCents, 0); }7}8 9// Ports defined by the core10export interface OrderRepository { save(order: Order): Promise<void> }11export interface PaymentGateway { charge(orderId: string, cents: number): Promise<{ ok: boolean }> }12 13// Use case depends only on ports14export class PlaceOrder {15  constructor(private orders: OrderRepository, private payments: PaymentGateway) {}16  async execute(id: string, items: Order["items"]) {17    const order = new Order(id, items);18    const result = await this.payments.charge(order.id, order.total());19    if (!result.ok) throw new Error("Payment declined");20    await this.orders.save(order);21    return order;22  }23}24 25// Adapter (outer layer)26export class PgOrderRepository implements OrderRepository {27  constructor(private pool: { query: (sql: string, params: unknown[]) => Promise<unknown> }) {}28  async save(order: Order) {29    await this.pool.query("INSERT INTO orders (id, total_cents) VALUES ($1, $2)", [order.id, order.total()]);30  }31}

Complexity and performance

Trade-offs

Variants and related techniques

Common mistakes

• Domain entities importing ORM annotations or HTTP types.

  Fix: Keep the core free of framework dependencies.

• Anemic domain models.

  Fix: Put business rules in entities and use cases, not controllers.

Interview questions

Practice problems