15/8/22, 21:43 Clean Coder Blog

The Clean Code Blog

by Robert C. Martin (Uncle Bob)

atom/rss feed
The Clean Architecture
Space War 13 August 2012
11-28-2021

Functional
Duplications
10-28-2021

Roots
09-25-2021

More On
Types
06-29-2021

On Types
06-25-2021

if-else-switch
03-06-2021

Pairing
Guidelines
01-17-2021
Over the last several years we’ve seen a whole range of ideas
Solid regarding the architecture of systems. These include:
Relevance
10-18-2020
Hexagonal Architecture (a.k.a. Ports and Adapters) by
Loopy Alistair Cockburn and adopted by Steve Freeman, and Nat
09-30-2020
Pryce in their wonderful book Growing Object Oriented
Conference Software
Conduct Onion Architecture by Jeffrey Palermo

https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html 1/15
15/8/22, 21:43 Clean Coder Blog

09-23-2020 Screaming Architecture from a blog of mine last year

The DCI from James Coplien, and Trygve Reenskaug.
Disinvitation BCE by Ivar Jacobson from his book Object Oriented
09-12-2020 Software Engineering: A Use-Case Driven Approach
REPL Driven
Design Though these architectures all vary somewhat in their details,
05-27-2020 they are very similar. They all have the same objective, which
A Little More is the separation of concerns. They all achieve this separation
Clojure by dividing the software into layers. Each has at least one
04-09-2020
layer for business rules, and another for interfaces.
A Little Clojure
04-06-2020
Each of these architectures produce systems that are:

A New Hope 1. Independent of Frameworks. The architecture does not

04-05-2020
depend on the existence of some library of feature laden
Open Letter to software. This allows you to use such frameworks as tools,
the Linux rather than having to cram your system into their limited
Foundation constraints.
11-08-2019
2. Testable. The business rules can be tested without the UI,
What They Database, Web Server, or any other external element.
Thought of 3. Independent of UI. The UI can change easily, without
Programmers. changing the rest of the system. A Web UI could be
11-03-2019
replaced with a console UI, for example, without changing
Circulatory the business rules.
10-31-2019
4. Independent of Database. You can swap out Oracle or SQL
Why Clojure? Server, for Mongo, BigTable, CouchDB, or something else.
08-22-2019
Your business rules are not bound to the database.
Why won't it... 5. Independent of any external agency. In fact your business
07-22-2019
rules simply don’t know anything at all about the outside
Classes vs. world.
Data
Structures The diagram at the top of this article is an attempt at
06-16-2019 integrating all these architectures into a single actionable
Types and idea.
Tests
06-08-2019 The Dependency Rule
737 Max 8
https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html 2/15
15/8/22, 21:43 Clean Coder Blog

05-18-2019 The concentric circles represent different areas of software. In

FP vs. OO List general, the further in you go, the higher level the software
Processing becomes. The outer circles are mechanisms. The inner circles
12-17-2018 are policies.
We, The
The overriding rule that makes this architecture work is The
Unoffended
12-16-2018
Dependency Rule. This rule says that source code
SJWJS
dependencies can only point inwards. Nothing in an inner
12-14-2018
circle can know anything at all about something in an outer
circle. In particular, the name of something declared in an
The Tragedy of
outer circle must not be mentioned by the code in the an
Craftsmanship.
08-28-2018
inner circle. That includes, functions, classes. variables, or
any other named software entity.
Too Clean?
08-13-2018
By the same token, data formats used in an outer circle should
Integers and not be used by an inner circle, especially if those formats are
Estimates generate by a framework in an outer circle. We don’t want
06-21-2018
anything in an outer circle to impact the inner circles.
Pickled State
06-06-2018 Entities
Craftsman,
Entities encapsulate Enterprise wide business rules. An entity
Craftswoman,
can be an object with methods, or it can be a set of data
Craftsperson
05-02-2018
structures and functions. It doesn’t matter so long as the
entities could be used by many different applications in the
FP vs. OO
04-13-2018
enterprise.

In The Large If you don’t have an enterprise, and are just writing a single
04-02-2018
application, then these entities are the business objects of the
We application. They encapsulate the most general and high-level
Programmers rules. They are the least likely to change when something
03-29-2018
external changes. For example, you would not expect these
Uncle Bob Fly- objects to be affected by a change to page navigation, or
In. security. No operational change to any particular application

Have I got a deal should affect the entity layer.

for you!
02-25-2018 Use Cases

https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html 3/15
15/8/22, 21:43 Clean Coder Blog

The The software in this layer contains application specific

Citizenship business rules. It encapsulates and implements all of the use
Argument cases of the system. These use cases orchestrate the flow of
01-18-2018 data to and from the entities, and direct those entities to use
Operating their enterprise wide business rules to achieve the goals of the
Behind the use case.
Power Curve
01-15-2018
We do not expect changes in this layer to affect the entities.
We also do not expect this layer to be affected by changes to
Excuses
12-18-2017
externalities such as the database, the UI, or any of the
common frameworks. This layer is isolated from such
Dbtails
12-09-2017
concerns.

Bobby Tables We do, however, expect that changes to the operation of the
12-03-2017
application will affect the use-cases and therefore the
Living on the software in this layer. If the details of a use-case change, then
Plateau some code in this layer will certainly be affected.
11-18-2017

Women In Interface Adapters

Demand
The software in this layer is a set of adapters that convert data
10-04-2017
from the format most convenient for the use cases and
Tools are not
entities, to the format most convenient for some external
the Answer
10-04-2017
agency such as the Database or the Web. It is this layer, for
example, that will wholly contain the MVC architecture of a
Test Contra-
GUI. The Presenters, Views, and Controllers all belong in
variance
10-03-2017
here. The models are likely just data structures that are
passed from the controllers to the use cases, and then back
The
from the use cases to the presenters and views.
Unscrupulous
Meme Similarly, data is converted, in this layer, from the form most
09-29-2017
convenient for entities and use cases, into the form most
Sierra Juliet convenient for whatever persistence framework is being used.
Foxtrot i.e. The Database. No code inward of this circle should know
09-26-2017
anything at all about the database. If the database is a SQL
Just Following database, then all the SQL should be restricted to this layer,
Orders and in particular to the parts of this layer that have to do with
08-28-2017
the database.
https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html 4/15
15/8/22, 21:43 Clean Coder Blog

Women in Also in this layer is any other adapter necessary to convert

Tech data from some external form, such as an external service, to
08-14-2017 the internal form used by the use cases and entities.
On the
Diminished Frameworks and Drivers.
Capacity to
The outermost layer is generally composed of frameworks and
Discuss Things
tools such as the Database, the Web Framework, etc.
Rationally
Generally you don’t write much code in this layer other than
08-10-2017
glue code that communicates to the next circle inwards.
Thought Police
08-09-2017 This layer is where all the details go. The Web is a detail. The
The Brain database is a detail. We keep these things on the outside
Problem where they can do little harm.
07-28-2017

Drive me to
Only Four Circles?
Toronto, Hal. No, the circles are schematic. You may find that you need
07-24-2017
more than just these four. There’s no rule that says you must
Pragmatic always have just these four. However, The Dependency Rule
Functional always applies. Source code dependencies always point
Programming inwards. As you move inwards the level of abstraction
07-11-2017
increases. The outermost circle is low level concrete detail. As
First-Class
you move inwards the software grows more abstract, and
Tests.
encapsulates higher level policies. The inner most circle is the
05-05-2017
most general.
Is Dr. Calvin in
the Room? Crossing boundaries.
03-16-2017

At the lower right of the diagram is an example of how we

Symmetry
cross the circle boundaries. It shows the Controllers and
Breaking
03-07-2017 Presenters communicating with the Use Cases in the next
Testing Like layer. Note the flow of control. It begins in the controller,
the TSA moves through the use case, and then winds up executing in
03-06-2017
the presenter. Note also the source code dependencies. Each
one of them points inwards towards the use cases.
TDD Harms
Architecture We usually resolve this apparent contradiction by using the
03-03-2017
Dependency Inversion Principle. In a language like Java, for
https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html 5/15
15/8/22, 21:43 Clean Coder Blog

Necessary example, we would arrange interfaces and inheritance

Comments relationships such that the source code dependencies oppose
02-23-2017 the flow of control at just the right points across the
Types and boundary.
Tests
For example, consider that the use case needs to call the
01-13-2017
presenter. However, this call must not be direct because that
The Dark Path
01-11-2017
would violate The Dependency Rule: No name in an outer
circle can be mentioned by an inner circle. So we have the use
TDD Lesson -
case call an interface (Shown here as Use Case Output Port) in
Terrain
the inner circle, and have the presenter in the outer circle
Generation
implement it.
01-09-2017

TDD Doesn't The same technique is used to cross all the boundaries in the
Work architectures. We take advantage of dynamic polymorphism
11-10-2016
to create source code dependencies that oppose the flow of
Dijkstra's control so that we can conform to The Dependency Rule no
Algorithm matter what direction the flow of control is going in.
10-26-2016

The Lurn What data crosses the boundaries.

09-01-2016
Typically the data that crosses the boundaries is simple data
The Churn
structures. You can use basic structs or simple Data Transfer
07-27-2016
objects if you like. Or the data can simply be arguments in
Mutation
function calls. Or you can pack it into a hashmap, or construct
Testing
it into an object. The important thing is that isolated, simple,
06-10-2016
data structures are passed across the boundaries. We don’t
Blue. No!
want to cheat and pass Entities or Database rows. We don’t
Yellow!
want the data structures to have any kind of dependency that
05-21-2016
violates The Dependency Rule.
Type Wars
05-01-2016
For example, many database frameworks return a convenient
Giving Up on data format in response to a query. We might call this a
TDD RowStructure. We don’t want to pass that row structure
03-19-2016
inwards across a boundary. That would violate The
Manhandled Dependency Rule because it would force an inner circle to
01-15-2016
know something about an outer circle.

https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html 6/15
15/8/22, 21:43 Clean Coder Blog

Stabilization So when we pass data across a boundary, it is always in the

Phases form that is most convenient for the inner circle.
01-14-2016

A Little Conclusion
Architecture
Conforming to these simple rules is not hard, and will save
01-04-2016
you a lot of headaches going forward. By separating the
Prelude to a
software into layers, and conforming to The Dependency
Profession
Rule, you will create a system that is intrinsically testable,
11-27-2015
with all the benefits that implies. When any of the external
The
parts of the system become obsolete, like the database, or the
Programmer's
web framework, you can replace those obsolete elements with
Oath
a minimum of fuss.
11-18-2015

The Force of
Pliers
11-01-2015

Future Proof
10-30-2015

Agile is not
now, nor was it
ever, Waterfall.
10-16-2015

VW
10-14-2015

WATS Line 54
10-05-2015

A Little
Structure
09-23-2015

Make the
Magic go
away.
08-06-2015

Pattern
Pushers
07-05-2015

https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html 7/15
15/8/22, 21:43 Clean Coder Blog

The Little
Singleton
07-01-2015

The First
Micro-service
Architecture
05-28-2015

Language
Layers
04-27-2015

Does
Organization
Matter?
04-15-2015

The MODE-B
Imperative
02-21-2015

They Called
them
Computers.
02-19-2015

'Interface'
Considered
Harmful
01-08-2015

The Cycles of
TDD
12-17-2014

OO vs FP
11-24-2014

Thorns around
the Gold
11-19-2014

The Obligation
of the
Programmer.
https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html 8/15
15/8/22, 21:43 Clean Coder Blog

11-15-2014

One Hacker
Way!
11-12-2014

Laughter in the
male
dominated
room.
10-26-2014

GOML-1,
Responsive
Design
10-08-2014

Clean Micro-
service
Architecture
10-01-2014

Microservices
and Jars
09-19-2014

The More
Things
Change...
09-18-2014

Test Time
09-03-2014

A Little About
Patterns.
06-30-2014

My Lawn
06-20-2014

Is TDD Dead?

Final Thoughts
about Teams.
06-17-2014

First
https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html 9/15
15/8/22, 21:43 Clean Coder Blog

05-19-2014

The Little
Mocker
05-14-2014

The Open
Closed
Principle
05-12-2014

Framework
Bound[2]
05-11-2014

When to Mock
05-10-2014

The Single
Responsibility
Principle
05-08-2014

Professionalism
and TDD
(Reprise)
05-02-2014

Test Induced
Design
Damage?
05-01-2014

When TDD
doesn't work.
04-30-2014

Monogamous
TDD
04-25-2014

Code
Hoarders
04-03-2014

The True
Corruption of
https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html 10/15
15/8/22, 21:43 Clean Coder Blog

Agile
03-28-2014

When Should
You Think?
03-11-2014

A Spectrum of
Trust
02-27-2014

Oh Foreman,
Where art
Thou?
02-23-2014

Where is the
Foreman?
02-21-2014

The Domain
Discontinuity
01-27-2014

Coding in the
Clink (9)
01-20-2014

Extreme
Programming,
a Reflection
12-10-2013

Novices. A
Coda
11-25-2013

Hordes Of
Novices
11-19-2013

Healthcare.gov
11-12-2013

The Careless
Ones
10-24-2013

https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html 11/15
15/8/22, 21:43 Clean Coder Blog

Dance you
Imps!
10-01-2013

A.T. FAIL!
09-26-2013

Test First
09-23-2013

Transformation
Priority and
Sorting
05-27-2013

The
Transformation
Priority
Premise
05-27-2013

Flash - TPP
05-27-2013

Fib. The T-P

Premise.
05-27-2013

There are
Ladies Present
03-22-2013

The Frenzied
Panic of
Rushing
03-11-2013

An Open and
Closed Case
03-08-2013

The
Pragmatics of
TDD
03-06-2013

https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html 12/15
15/8/22, 21:43 Clean Coder Blog

The Start-Up
Trap
03-05-2013

The Principles
of
Craftsmanship
02-10-2013

The Humble
Craftsman
02-01-2013

The Laborer
and the
Craftsman
01-30-2013

FP Basics E4
01-29-2013

FP Basics E3
01-07-2013

FP Basics E2
01-02-2013

Brave New
Year
12-29-2012

FP Basics E1
12-22-2012

Three
Paradigms
12-19-2012

The New CTO

09-06-2012

Functional
Programming
for the Object
Oriented
Programmer
08-24-2012

https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html 13/15
15/8/22, 21:43 Clean Coder Blog

The Clean
Architecture
08-13-2012

NO DB
05-15-2012

Why is
Estimating so
Hard?
04-20-2012

After the
Disaster
04-18-2012

Service
Oriented
Agony
02-01-2012

The Ruby
Colored Box
01-31-2012

Fecophiles
01-20-2012

The Letter
01-12-2012

Flipping the Bit

01-11-2012

The
Barbarians are
at the Gates
12-11-2011

Clean
Architecture
11-22-2011

Double Entry
Bookkeeping
Dilemma.

https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html 14/15
15/8/22, 21:43 Clean Coder Blog

Should I Invest
or Not?
11-06-2011

Simple Hickey
10-20-2011

Screaming
Architecture
09-30-2011

Bringing
Balance to the
Force
01-19-2011

What Software
Craftsmanship
is about
01-17-2011

https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html 15/15