Clean architecture

Separation of consern, isolating pieces of code that repeats and decoupling responsabilities from differents parts of the code base seems to be a common approach among experienced developers. Therefore, through the experience comes the opinionated approach, some developers might decide to create specific directories or others might use longer file names to express intent.

I have published my own thoughts on that matter as well, and then I discovered the clean architecture book [1], which dives much deeper on that subject and also explores the pros of having a architecture in place.

Table of contents

  1. Architectural styles compared to the clean architecture
  2. Clean architecture in a glance
  3. Implementation details
  4. References

Architectural styles compared to the clean architecture

As I first started my path through the clean architecture I often found asking myself: is hexagonal architecture [2] the same as clean architecutre?

The clean architecture, shares decisions compared with the hexagonal architecture, as [3] states that the clean architecture is an attempt to integrate the hexagonal architecture and other as well, named:

  1. Hexagonal architecture / Onion architecutre
  2. Screaming architecture
  3. DCI
  4. BCE

The clean architecture is an attempt to combine those styles together to produce an output.

Clean architecture in a glance

Clean architecture focuses on the separation of concerns and also it takes care of the evolution of the code, the evolution is one of key aspects of the clean architecture as it has a dedicated section in the first chapter, “The Total Cost of Owning a Mess”, [1] that depicts the fact that the productivity degrades as the time goes. Which is caused by the lack of care with code and also the software maintainability.

The following diagram taken from [3] depicts the clean architecture overview.

Clean architecture diagram

The structure I am following next is the same presented by [3], so then I can follow some line of thought, besides that I also give my contribution to each section.

The dependency rule

The depdency rule follows basicaly the same principle as the layered architecture. [4]. Anything in the inner circle should not know anything about the outer circle, the same principle in the layered architecture, to keep layers following a same direction.


Entities are the objects that represents the business.

Use cases

Use cases are the business rule that the application executes. Here is the place to add the business logic. In a comparison with MVC, the use case, is the place as where the controller is.

Frameworks and adapters

Opposed to what MVC frameworks impose in the architecture for web applications, the clean architecture does not take the framework as something that is the core of the application, instead the framework is something that is a “implementation detail”, meaning that it is possible to change the framework choice if needed, without impacting the use cases. The same way as the framework is a detail the database is as well [3].

Implementaion details

The book comes with code examples to ilustrate the scenarios and also to make statements on the point being made, therefore, there is no folder structure, file name convention or waht so ever to “glue the pieces together”. This is a point to improve, but not necessary in the book. I would argue that for any programmer with a few years of experience, the concepts given are understandable, but there are programmers like me that like some sort of guide lines so the it is possible to compare implementations.

[5] provides a implemention of clean architecture using java. It goes along the clean architecture definitions and depicts folder structure, files, boundaries, abstractions and also reinforce definitions on the use cases.


  1. [1]R. C. Martin, “Clean Architecture A Craftsman’s Guide To Software Structure And Design,” 2017 [Online]. Available at: [Accessed: 2020-Jun-11AD]
  2. [2]A. Cockburn, “Hexagonal architecture,” 2012 [Online]. Available at: [Accessed: 13-Aug-2012]
  3. [3]R. C. Martin, “The Clean Architecture,” 2020 [Online]. Available at: [Accessed: 07-Oct-2020]
  4. [4]R. Mark, Software Architecture Patterns. O’Reilly Media, Inc, 2015.
  5. [5]T. Hombergs, “Get Your Hands Dirty on Clean Architecture - A Hands-on Guide to Creating Clean Web Applications with Code Examples in Java,” 2020 [Online]. Available at: [Accessed: 30-Jan-2020]
Share this on