Clean architecture - Hexagonal architecture, Screaming architecture, DCI, BCE

Last updated Apr 22, 2023 Published Aug 18, 2023

The content here is under the Attribution 4.0 International (CC BY 4.0) license

Separation of concern, isolating pieces of code that repeat and decoupling responsibilities from different parts of the code base seems to be a common approach among experienced developers. Maximiliano Contieri for example, named coupling the only software design. 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 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 an architecture in place.

As a companion for this post, I recommend the talk “The Principles of Clean Architecture” by Uncle Bob Martin as well as the playlist that I built on software architecture in general [2].

Architectural styles compared to the clean architecture

As I first started my path through clean architecture I often found myself asking myself: is hexagonal architecture [3] the same as clean architecture? The clean architecture, shares decisions compared with the hexagonal architecture, as [4] states that the clean architecture is an attempt to integrate the hexagonal architecture and others as well, named:

  1. Hexagonal architecture / Onion architecture
  2. Screaming architecture
  3. DCI (Data, Context and Interaction)
  4. BCE (Boundary, Control, Entity) [5]

Clean architecture is an attempt to combine those styles to produce an output, in short, it tries to combine the good parts of every other style into one.

Clean architecture at a glance

Clean architecture focuses on the separation of concerns and also takes care of the evolution of the code, the evolution is one of the key aspects of 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 [4] depicts the clean architecture overview.

Clean architecture diagram

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

The dependency rule

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


Entities are the objects that represent the business.

Use cases

Use cases are the business rules that the application executes. Here is the place to add the business logic. In a comparison with MVC, the use case is the place 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 an “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 [4].

Implementation details

The book comes with code examples to illustrate the scenarios and also to make statements on the point being made, therefore, there is no folder structure, file name convention or whatsoever 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 who like some sort of guidelines so that it is possible to compare implementations.

[7] provides an implementation of clean architecture using java. It goes along the clean architecture definitions and depicts folder structure, files, boundaries, and abstractions and also reinforces 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]M. Marabesi, “Software architecture,” 2020 [Online]. Available at: [Accessed: 14-Aug-2021]
  3. [3]A. Cockburn, “Hexagonal architecture,” 2012 [Online]. Available at: [Accessed: 13-Aug-2012]
  4. [4]R. C. Martin, “The Clean Architecture,” 2020 [Online]. Available at: [Accessed: 07-Oct-2020]
  5. [5]I. Jacobson, “The use-case construct in object-oriented software engineering,” in Scenario-based design: envisioning work and technology in system development, 1995, pp. 309–336.
  6. [6]R. Mark, Software Architecture Patterns. O’Reilly Media, Inc, 2015.
  7. [7]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]