loading…

Clean Architecture

A software architecture pattern synthesized by robert c martin that integrates multiple layered architectural approaches into a unified system design philosophy. Clean Architecture organizes systems into concentric circles where dependencies flow inward, enabling testable, maintainable, and framework-independent software.

UI  ->  use-cases  ->  entities
         ^             |
         +-- adapters -+        dependencies point INWARD only

Core Principles

The Dependency Rule

The fundamental organizing principle: source code dependencies can only point inwards. Nothing in an inner circle can know anything about an outer circle. This includes functions, classes, variables, or any named software entity. Data formats from outer circles must not be used by inner circles.

Four-Layer Structure

1. Entities (Innermost) — Enterprise-wide business rules that could be used across multiple applications. The most stable layer, least likely to change due to external factors.

2. Use Cases — Application-specific business rules that orchestrate data flow between entities and direct them to achieve specific goals. Changes here affect the application but not entities.

3. Interface Adapters — Convert data between formats convenient for use cases/entities and external systems. Contains MVC components, presenters, views, controllers. All database access code belongs here.

4. Frameworks and Drivers (Outermost) — Database, web frameworks, external tools. Contains mostly glue code connecting to inner layers. “Details” that can be replaced with minimal impact.

System Characteristics

Clean Architecture produces systems that are:

1. Independent of Frameworks — Frameworks serve as tools rather than architectural constraints
2. Testable — Business rules testable without UI, database, or external dependencies
3. Independent of UI — UI changes don’t affect business rules
4. Independent of Database — Business rules not bound to specific database technologies
5. Independent of External Agencies — Business rules know nothing about the outside world

Boundary Crossing

Communication across layer boundaries uses the dependency inversion principle to maintain the dependency rule while allowing necessary data flow. Interfaces in inner circles are implemented by outer circles, using dynamic polymorphism to oppose control flow direction.

Data crossing boundaries should be simple structures (DTOs, function arguments) without dependencies that violate the dependency rule.

Architectural Synthesis

Clean Architecture integrates concepts from:

• hexagonal architecture (Ports and Adapters) by alistair cockburn
• onion architecture by jeffrey palermo
• Screaming Architecture by robert c martin
• DCI by james coplien and trygve reenskaug
• BCE by ivar jacobson

All these patterns share the objective of separation of concerns through layered design with protected business rules.

Failure Modes

Symptom	Root cause	Fix
Framework bleeds into core logic	Entities import framework types	Entities depend on nothing; adapters translate at the edge
Database schema drives design	Data model conflated with domain model	Repository ports own persistence; entities never see SQL
Layer skipped ‘just this once’	No enforcement of the rule	Automated import rules (dependency-cruiser/import-linter) fail the build

Rule of Thumb

If you can name the framework a module serves, that module is in the wrong layer - the core names abstractions, only adapters name vendors.

Related Concepts

• dependency rule
• dependency inversion principle
• hexagonal architecture
• onion architecture
• agent harness engineering
• cordis framework
• deepseek harness

[source: uncle-bob-clean-architecture-2012]