---
title: "Clean Architecture"
description: "Uncle Bobs dependency-inward organizing rule applied to agent systems: source dependencies point toward stable abstractions."
section: "concepts"
type: "concept"
created: "2026-08-25"
updated: "2026-08-30"
confidence: "high"
tags: ["principle", "workflow"]
canonical: "https://pyweb.dev/wiki/clean-architecture"
---
# Clean Architecture

A software architecture pattern synthesized by [robert c martin](/wiki/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.


```text
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](/wiki/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](/wiki/hexagonal-architecture) (Ports and Adapters) by [alistair cockburn](/wiki/alistair-cockburn)  
- [onion architecture](/wiki/onion-architecture) by [jeffrey palermo](/wiki/jeffrey-palermo)
- Screaming Architecture by [robert c martin](/wiki/robert-c-martin)
- DCI by [james coplien](/wiki/james-coplien) and [trygve reenskaug](/wiki/trygve-reenskaug)
- BCE by [ivar jacobson](/wiki/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](/wiki/dependency-rule)
- [dependency inversion principle](/wiki/dependency-inversion-principle)
- [hexagonal architecture](/wiki/hexagonal-architecture)
- [onion architecture](/wiki/onion-architecture)
- [agent harness engineering](/wiki/agent-harness-engineering)
- [cordis framework](/wiki/cordis-framework)
- [deepseek harness](/wiki/deepseek-harness)

 [[source: uncle-bob-clean-architecture-2012]](/wiki/raw/articles/uncle-bob-clean-architecture-2012)

---

## Agent Navigation

cluster: person (170 pages) | betweenness: 1624.5

### References (outbound)
- [Robert C. Martin (Uncle Bob)](https://pyweb.dev/wiki/robert-c-martin.md)
- [Dependency Inversion Principle](https://pyweb.dev/wiki/dependency-inversion-principle.md)
- [Hexagonal Architecture](https://pyweb.dev/wiki/hexagonal-architecture.md)
- [Onion Architecture](https://pyweb.dev/wiki/onion-architecture.md)
- [James Coplien](https://pyweb.dev/wiki/james-coplien.md)
- [Ivar Jacobson](https://pyweb.dev/wiki/ivar-jacobson.md)
- [Dependency Rule](https://pyweb.dev/wiki/dependency-rule.md)
- [Agent Harness Engineering](https://pyweb.dev/wiki/agent-harness-engineering.md)
- [Cordis Framework](https://pyweb.dev/wiki/cordis-framework.md)
- [DeepSeek Harness](https://pyweb.dev/wiki/deepseek-harness.md)

### Referenced by (inbound)
- [Agent Harness Engineering](https://pyweb.dev/wiki/agent-harness-engineering.md)
- [Codex Harness Architecture](https://pyweb.dev/wiki/codex-harness-architecture.md)
- [Dependency Inversion Principle](https://pyweb.dev/wiki/dependency-inversion-principle.md)
- [Dependency Rule](https://pyweb.dev/wiki/dependency-rule.md)
- [Five Debts of Agentic Engineering](https://pyweb.dev/wiki/five-debts-of-agentic-engineering.md)
- [Software Engineering Fundamentals for Agents](https://pyweb.dev/wiki/software-engineering-fundamentals-for-agents.md)
- [Alistair Cockburn](https://pyweb.dev/wiki/alistair-cockburn.md)
- [Ivar Jacobson](https://pyweb.dev/wiki/ivar-jacobson.md)
- [James Coplien](https://pyweb.dev/wiki/james-coplien.md)
- [Jeffrey Palermo](https://pyweb.dev/wiki/jeffrey-palermo.md)
- [Nat Pryce](https://pyweb.dev/wiki/nat-pryce.md)
- [Robert C. Martin (Uncle Bob)](https://pyweb.dev/wiki/robert-c-martin.md)
- [Steve Freeman](https://pyweb.dev/wiki/steve-freeman.md)
- [Trygve Reenskaug](https://pyweb.dev/wiki/trygve-reenskaug.md)

### Evidence (verified primary sources)
- [uncle-bob-clean-architecture-2012](https://pyweb.dev/wiki/raw/articles/uncle-bob-clean-architecture-2012.md) | origin: https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html | ingested: 2026-08-25 | sha256: b99ae450b5981dbee264aec42701b920ce96ccedea01d03243ea48c414442379

### Machine endpoints
- Knowledge graph: https://pyweb.dev/api/graph.json
- Graph analysis: https://pyweb.dev/api/graph-analysis.json
- Context index: https://pyweb.dev/llms.txt