Clean Architecture

May 10, 2026··
15 min read
Open full tree
Clean ArchitectureFundamentals of Clean ArchitectureBuilding Clean ArchitecturesPractical ApplicationsAdvanced Topics

Clean Architecture — A Comprehensive Guide

Clean Architecture is a software architecture paradigm that emphasizes separation of concerns, maintainability, testability, and independence from frameworks, UI, databases, and infrastructure. It provides a set of organizing principles and structural guidelines that help teams build systems that are easier to understand, change, and evolve.

This article is a deep dive: history and roots, core principles and theoretical foundations, architecture components and boundaries, practical patterns and implementations, testing and deployment implications, trade-offs and pitfalls, modern adaptations, and a practical example you can use as a starting point.

Contents

  • History and intellectual roots
  • Key concepts and principles
  • The Clean Architecture layers and components
  • Dependency Rule and Dependency Inversion
  • Typical folder/module layouts (examples)
  • Example implementations (TypeScript/Node and Python)
  • Testing strategies
  • Practical applications and real-world usage
  • Benefits, trade-offs and anti-patterns
  • Transitioning legacy systems & migration strategies
  • Clean Architecture in modern contexts: microservices, serverless, event-driven systems
  • Checklist and recommended practices
  • Further reading and resources

1. History and intellectual roots

Clean Architecture did not emerge in isolation. It synthesizes earlier architectural ideas and software engineering principles:

  • Layered Architecture (traditional n-tier designs) — long used in enterprise systems.
  • Hexagonal Architecture / Ports and Adapters — Alistair Cockburn (mid-2000s): decouples application core from external concerns via ports (interfaces) and adapters (implementations).
  • Onion Architecture — Jeffrey Palermo (around 2008): concentric layers with domain model at the center, infrastructure on the outside.
  • Domain-Driven Design (Evans, 2003): focus on a rich domain model and ubiquitous language.
  • SOLID principles (Robert C. Martin and others): single responsibility, open/closed, Liskov substitution, interface segregation, dependency inversion.
  • Clean Architecture — Robert C. Martin (Uncle Bob) popularized the explicit Clean Architecture concentric-layer model and Dependency Rule in his 2012–2017 writings and book "Clean Architecture" (2017).

Clean Architecture is, in effect, an evolution and synthesis of these ideas designed to make systems resilient to change and technology churn.

2. Key concepts and principles

These are the cardinal ideas underlying Clean Architecture:

  • Separation of concerns: isolate business rules from UI, infrastructure, and frameworks.
  • Independence from frameworks: the domain and use cases should not depend on frameworks (so frameworks can be swapped or upgraded).
  • Dependency Rule: source code dependencies must always point inward (toward higher-level policies). Nothing in an inner circle should know about anything in an outer circle.
  • Dependency Inversion (DIP): high-level modules should not depend on low-level modules; both should depend on abstractions.
  • Single responsibility (SRP): each component/module should have one reason to change.
  • Testability: business rules and use cases should be unit-testable without the infrastructure (databases, UI, web servers).
  • Boundaries via interfaces (ports): outer layers implement interfaces defined by inner layers to allow inversion and isolation.
  • Entities and use cases: entities represent enterprise-wide business rules; use cases implement application-specific business rules.
  • Independent of UI and database: the same core can be used with different UIs and persistence mechanisms.

3. The Clean Architecture layers and components

A common depiction is concentric circles. From center to outermost:

  1. Entities (Enterprise Business Rules)

    • Domain objects, business rules, invariants.
    • Highly stable, independent of technology.
    • Example: Customer, Invoice, Order entities and their validation/compute logic.

  2. Use Cases / Interactors (Application Business Rules)

    • Application-specific logic—coordinating entities to accomplish tasks.
    • Orchestrates actions, enforces policies, input/output boundaries.
    • Example: CreateOrderUseCase, AuthenticateUser, CalculateInvoice.

  3. Interface Adapters / Presenters / Controllers / Gateways

    • Adapt data from external forms (DB, web requests, UI) into the format required by use cases/entities.
    • Implement interfaces defined by inner layers (e.g., repository interfaces).
    • Presenters/Controllers format data for the UI.

  4. Frameworks & Drivers (External Interfaces)

    • Web frameworks, UI, DB, third-party libraries, devices.
    • These are the least stable and most changeable parts and should be isolated from the domain.

Key relationships:

  • Inner layers define interfaces; outer layers implement those interfaces.
  • Data flows inwards for requests; outputs flow outwards through presenters/adapters.

Common components and terms:

  • Controller: receives input (e.g., HTTP), maps to input model, passes to use case.
  • Interactor / Use Case: performs business logic for a given application operation.
  • Presenter/ViewModel: prepares output data structures for the UI.
  • Gateway / Repository: abstracts persistence and external service calls.

4. The Dependency Rule and Dependency Inversion

The Dependency Rule: source code dependencies can only point inwards. No inner layer depends on outer layers. This is enforced by programming to interfaces or abstractions.

Dependency Inversion Principle (DIP) is the mechanism:

  • Inner layer defines an abstraction (e.g., interface IOrderRepository).
  • Outer layer provides concrete implementation (e.g., SqlOrderRepository) and is injected at runtime.
  • High-level policies (use cases) depend on abstractions, not concrete implementations.

Benefits:

  • Replace databases, frameworks, UIs with minimal or no change to core logic.
  • Easier to unit test the use cases by mocking the abstractions.

Implementation mechanisms:

  • Interfaces in statically typed languages (Java, C#, TypeScript).
  • Protocols or duck-typing in dynamically typed languages (Python, Ruby) combined with dependency injection.
  • Inversion-of-Control (IoC) containers or manual dependency injection at composition root.

5. Typical folder/module layouts

There are many valid ways to organize code. Two common approaches: vertical by feature and horizontal by layer.

Example horizontal (conventional Clean Architecture):

/src /entities Order.ts Customer.ts /usecases CreateOrder.ts GetOrder.ts /adapters /controllers OrderController.ts /presenters OrderPresenter.ts /gateways OrderRepositoryImpl.ts /framework /db PostgresClient.ts /web ExpressServer.ts /config CompositionRoot.ts

Example vertical (feature-first), sometimes simpler for large systems:

/src /orders entities/Order.ts usecases/CreateOrder.ts adapters/controllers/OrderController.ts adapters/gateways/OrderRepositoryImpl.ts presenters/OrderPresenter.ts /users ...

Feature-first often scales better in large codebases by co-locating feature code.

6. Example implementations

Below are simplified examples showing the pattern in two languages.

Note: these are illustrative snippets, not complete production apps.

A. TypeScript / Node (simplified)

Folder structure:

  • src/
    • entities/Order.ts
    • usecases/CreateOrder.ts
    • interfaces/IOrderRepository.ts
    • adapters/OrderRepositoryPg.ts
    • controllers/OrderController.ts
    • composition/CompositionRoot.ts

IOrderRepository.ts

TypeScript
1export interface IOrderRepository { 2 save(order: Order): Promise<void>; 3 findById(id: string): Promise<Order | null>; 4}

Order.ts

TypeScript
1export class Order { 2 constructor(public id: string, public items: {sku: string, qty: number}[]) {} 3 total() { /* business logic */ } 4}

CreateOrder.ts (use case)

TypeScript
1import { IOrderRepository } from '../interfaces/IOrderRepository'; 2import { Order } from '../entities/Order'; 3 4export class CreateOrder { 5 constructor(private orderRepo: IOrderRepository) {} 6 7 async execute(input: {id: string, items: any[]}) { 8 const order = new Order(input.id, input.items); 9 // domain validations 10 await this.orderRepo.save(order); 11 return { success: true, orderId: order.id }; 12 } 13}

OrderRepositoryPg.ts (outer layer persistence)

TypeScript
1import { IOrderRepository } from '../interfaces/IOrderRepository'; 2import { Order } from '../entities/Order'; 3export class OrderRepositoryPg implements IOrderRepository { 4 constructor(private pgPool: any) {} 5 async save(order: Order) { 6 // convert order -> db record, call pg client 7 } 8 async findById(id: string) { /* ... */ } 9}

CompositionRoot.ts

TypeScript
1import { CreateOrder } from '../usecases/CreateOrder'; 2import { OrderRepositoryPg } from '../adapters/OrderRepositoryPg'; 3 4const pgPool = createPgPool(); 5const orderRepo = new OrderRepositoryPg(pgPool); 6export const createOrderUseCase = new CreateOrder(orderRepo);

Controller (adapter)

TypeScript
1import { createOrderUseCase } from '../composition/CompositionRoot'; 2export async function postOrder(req, res) { 3 const result = await createOrderUseCase.execute(req.body); 4 res.json(result); 5}

B. Python (illustrative)

interfaces.py

Python
1from abc import ABC, abstractmethod 2 3class OrderRepository(ABC): 4 @abstractmethod 5 def save(self, order): pass 6 @abstractmethod 7 def get(self, id): pass

entities.py

Python
1class Order: 2 def __init__(self, id, items): 3 self.id = id 4 self.items = items 5 def total(self): ...

usecases.py

Python
1class CreateOrder: 2 def __init__(self, repo: OrderRepository): 3 self.repo = repo 4 def execute(self, order_data): 5 order = Order(order_data['id'], order_data['items']) 6 # validations... 7 self.repo.save(order) 8 return {'order_id': order.id}

adapters.py

Python
1class PostgresOrderRepository(OrderRepository): 2 def __init__(self, db): 3 self.db = db 4 def save(self, order): 5 # transform and persist 6 pass

app.py (composition root)

Python
1db = connect_db() 2repo = PostgresOrderRepository(db) 3create_order = CreateOrder(repo) 4 5# wire to Flask route 6@app.route('/orders', methods=['POST']) 7def create_order_route(): 8 return jsonify(create_order.execute(request.json))

7. Testing strategies

Because of the separation of concerns and the Dependency Rule, testing is straightforward and effective.

Types of tests:

  • Unit tests: test entities and use cases in isolation by mocking dependencies (repositories, external services).
  • Integration tests: test interactions with infrastructure (DB, message brokers) with lightweight containers or test doubles.
  • Acceptance/end-to-end tests: verify system behavior via HTTP endpoints or UI automation.
  • Contract tests: useful in microservices to ensure adapters meet expectations.

Guidelines:

  • Test use cases without needing a database by mocking repositories.
  • Use in-memory fakes or test doubles for fast integration tests.
  • Keep tests fast and deterministic — core logic should be pure and not depend on external state.
  • Use dependency injection/composition root to swap real implementations with fakes during tests.

Example unit test (pseudo-JS)

TypeScript
1test('CreateOrder saves order', async () => { 2 const fakeRepo = { save: jest.fn(), findById: jest.fn() }; 3 const createOrder = new CreateOrder(fakeRepo); 4 const result = await createOrder.execute({ id: '1', items: [] }); 5 expect(fakeRepo.save).toHaveBeenCalled(); 6 expect(result.orderId).toBe('1'); 7});

8. Practical applications and real-world usage

Where Clean Architecture shines:

  • Complex business domains where business rules are stable and require rigorous testing.
  • Systems expected to evolve: switching databases, multiple UIs (web, mobile), third-party services.
  • Teams working on long-lived products; facilitates onboarding, code ownership handover.
  • Microservice ecosystems where independent services encapsulate business capabilities.

Examples:

  • Banking and financial applications with complex domain logic and regulatory requirements.
  • Healthcare systems: core rules must be stable, verifiable, and decoupled.
  • Large e-commerce platforms: order/inventory domain logic isolated from payment gateways and UI changes.

Frameworks and projects that align with Clean Architecture:

  • Spring Boot or Micronaut services using interfaces and layered modules
  • .NET projects structured with Core (domain) projects, Application projects, Infrastructure projects
  • Node.js projects using feature modules and dependency injection (NestJS aligns well)
  • Many open-source templates and starter kits for Clean Architecture in multiple languages

9. Benefits, trade-offs, and anti-patterns

Benefits

  • Testability: easier to unit-test domain and application logic.
  • Replaceability: swap databases, UIs, or frameworks with minimal impact.
  • Maintainability: clear separation of concerns reduces coupling.
  • Longevity: protects core business rules from tech churn.

Trade-offs and costs

  • Initial complexity and boilerplate: interfaces, many layers, composition roots.
  • Over-engineering risk: small/simple projects may get slowed by unnecessary abstractions.
  • Learning curve: developers must understand inversion of control and boundary patterns.
  • Performance: extra layers/indirection can incur small overheads (usually negligible compared to network/db costs).

Common anti-patterns

  • Anemic Domain Model: pushing business rules into services or use cases and leaving domain objects as data bags — defeats the purpose of entities.
  • Framework-oriented design: letting a web framework dictate the domain model and control flow.
  • Deep layering for trivial features: adding layers for features that don't need them.
  • Violating dependency rule: referencing infrastructure from domain code.

Rule of thumb: apply Clean Architecture pragmatically. Use it where the benefits outweigh the complexity.

10. Transitioning a legacy system — migration strategies

Migrating a monolith or legacy system to Clean Architecture can be done incrementally.

Strategies:

  • Strangler Fig pattern: add a new system/core that implements new behavior; route new traffic to it; gradually replace legacy components.
  • Identify seams: isolate business logic that can be extracted as use cases/entities; create interfaces and adaptors.
  • Add abstraction layers around key external dependencies (DB, messaging), then refactor internals to depend on those abstractions.
  • Start with a single bounded context or feature as a pilot.
  • Maintain tests at every step to ensure behavior remains intact.

Steps

  1. Create a "Core" module with entity definitions and basic use cases for a slice of functionality.
  2. Add interfaces for repositories used by the core.
  3. Implement adapters in the legacy codebase to satisfy new interfaces.
  4. Gradually move implementations from legacy to new adapters, swap via composition root.
  5. Repeat for other features until legacy system's responsibilities are migrated.

Pitfalls

  • Trying to refactor everything at once (big-bang) — risky.
  • Lacking a test harness — make sure behavior is covered before changing internals.

11. Clean Architecture in modern contexts

A. Microservices

  • Each microservice can be organized with a Clean Architecture core to encapsulate its business rules.
  • Bounded contexts align well with service boundaries.
  • Inter-service contracts and API/interfaces should be treated as outer layer concerns.

B. Serverless / Functions

  • Clean Architecture still applies: the function handler is an outer adapter that composes and calls a core use case.
  • Restrict function logic to orchestration and keep business rules in core modules for reuse and testability.

C. Event-driven systems

  • Events are the input boundary; event processors are controllers/adapters that call use cases.
  • Domain events may be emitted by use cases and handled by adapters or other use cases (possibly in different services).
  • Consider idempotency, eventual consistency, and sagas/choreography for cross-cutting transactional flows.

D. Cloud-native

  • Infrastructure concerns (cloud services, managed databases) are adapters.
  • Use Infrastructure as Code and separate composition/deployment logic from domain code.

E. UI-rich applications (web SPAs, mobile)

  • Backend core remains the single source of truth; multiple UI adapters (REST, GraphQL, gRPC) can be provided.
  • Presenters/ViewModels adapt the use case outputs to UI-specific formats.

12. Checklist and recommended practices

When implementing or evaluating a Clean Architecture solution:

  • Domain first: ensure entities encapsulate business rules.
  • Use cases instead of fat controllers: controllers should only orchestrate mapping input to use cases.
  • Define repository/service interfaces inside the application/core layer.
  • Implement persistence and external services in outer layers and inject them into the core.
  • Keep frameworks/framework logic out of domain and use-case code.
  • Use a composition root to wire dependencies once (preferably at application startup).
  • Favor explicit interfaces and small, focused modules.
  • Keep modules cohesive and respect SRP.
  • Ensure tests exist for entities and use cases that run without infrastructure.
  • Avoid premature optimization — start pragmatic and evolve.
  • Prefer feature modules (vertical slices) for large systems where feasible.
  • Document the boundaries and conventions for team clarity.

13. Example: small end-to-end walkthrough (high level)

Goal: Create a simple REST API for orders that uses Clean Architecture principles.

  1. Entities: Order (id, items, status), with business rules: cannot finalize an order with zero items.
  2. Use Case: CreateOrder — validates input, constructs Order entity, calls OrderRepository.save.
  3. Interface: OrderRepository (save, getById).
  4. Adapter: PostgresOrderRepository implements OrderRepository, mapping Order -> DB rows.
  5. Controller: OrdersController reads HTTP POST, maps to DTO, calls CreateOrder, returns JSON.
  6. Composition Root: wires PostgresOrderRepository into CreateOrder and registers controller with Express/Flask.

Testing:

  • Unit test CreateOrder with a mock repository.
  • Integration test persistence via test DB (e.g., Dockerized Postgres).
  • End-to-end test HTTP POST returns expected response and persists order.

This flow isolates the domain rules (Order validations) from web and DB concerns.

14. Common patterns and variants

  • Hexagonal (Ports & Adapters): closely aligned, emphasizes ports (interfaces) & adapters; more explicit about inbound and outbound ports.
  • Onion: emphasizes domain model at center and rings of responsibilities.
  • Vertical Feature Modules: grouping all layers per feature/vertical, beneficial for scaling teams and features.
  • CQRS + Clean Architecture: read and write models implemented as separate use-case sets; use case layer can host command handlers and query handlers.
  • Event Sourcing: domain events are first-class citizens and can be emitted by use cases/entities; event store is an outer adapter.

15. Future implications / evolution

  • The core principles remain robust as infrastructure evolves. Whether using containers, serverless, or emerging frameworks, protecting the domain from tech churn is valuable.
  • Tooling and framework support will continue to improve: opinionated frameworks (e.g., NestJS, Micronaut) offer patterns that map closely to Clean Architecture.
  • Increasing emphasis on developer velocity and micro-frontends may cause more teams to adopt feature-based modularization rather than strict horizontal layering.
  • With more distributed and event-driven systems, attention to boundaries, idempotency, and consistency models will increase. Clean Architecture's emphasis on explicit boundaries and contracts will be crucial.
  • Machine learning and data-intensive applications will require careful thought to separate model training/inference infrastructure from core business rules to avoid coupling.

16. Further reading and resources

  • "Clean Architecture" — Robert C. Martin (book)
  • "Domain-Driven Design" — Eric Evans (book)
  • "Patterns of Enterprise Application Architecture" — Martin Fowler
  • "Hexagonal Architecture" / "Ports and Adapters" — Alistair Cockburn (articles)
  • "Onion Architecture" — Jeffrey Palermo (blog)
  • Numerous language-specific Clean Architecture templates and example repos on GitHub (search for "clean architecture [language]").

17. Final recommendations

  • Use Clean Architecture to protect business rules from change and to make your system testable and maintainable.
  • Apply pragmatically: avoid creating needless complexity for small/simple apps.
  • Prefer vertical/feature-based modularization for large codebases; keep boundaries clear.
  • Invest in tests and a clear composition root to maximize the benefits.
  • Teach team members the core concepts (dependency rule, DIP) and maintain code conventions to prevent boundary erosion.

Clean Architecture is less about rigidly drawing circles and more about establishing durable boundaries and disciplined dependency directions. When applied thoughtfully, it dramatically improves a system’s capacity to adapt to change while preserving correctness and developer productivity.