Clean Architecture

This is part of a series, start here!

This is Uncle Bob’s attempt at synthesize previous architectural patterns and concepts.

Based on a common thread between Ports & Adapters, Onion, EBI, he wrote an article as ‘an attempt at integrating all these architectures into a single actionable idea’.¹

High level

The original article starts with a diagram similar to this:

Project structure

At face value, the diagram seems to suggest a project structure as such:

1
Entities
2
├── Tenant
3
├── Landlord
4
├── Rent
5
Repositories
6
├── TenantRepo
7
├── LandlordRepo
8
├── RentRepo
9
UseCases
10
├── PayRent
11
├── RequestRent
12
├── RequestRepair
13
├── CalculateRent
14
...

There are however a couple of shortcomings here:

• Low cohesion: Modify one Use Case, and you’ll have to change code in three different modules
• No clear purpose: A newcomer would have to dig through the directory structure to know what the application is for

Borrowing some key concepts like Bounded Context from DDD, the previous system can be represented as such:

1
Tenant
2
├── Tenant
3
├── TenantRepo
4
├── PayRent
5
├── RequestRepair
6
Landlord
7
├── Landlord
8
├── LandlordRepo
9
├── RequestRent
10
Rent
11
├── Rent
12
├── RentRepo
13
├── CalculateRent
14
...

Low level

There’s a pretty useful diagram in the slides Bob uses in his conferences.

Cool, but a bit overwhelming. Let’s start with Entity and Interactor² and build the diagram with concepts from other notable architectures.³

Think of the Interactor as the implementation of a use case of the application.

Thanks to Ports & Adapters, we know that a use case should be defined as an abstraction to ensure inwards dependency.

So if a use case is an abstract concept of ‘what needs to be done’, the Interactor is the concrete implementation of ‘how exactly it will happen’.

Entities usually require some sort of persistence, we can use a Driven Port/Adapter pair for that.

Let’s also represent the actor that will use the Driver Port from before, as well as the data structure (DTO) that will be shared between it and the Interactor.

The controller could just as well be a CLI or a GUI.

Using a DTO here allows us to avoid exposing the Domain Entities outside the boundaries of the application. Speaking of boundaries.

The red line marks the limit of our application logic and separates it from the pieces of the system that are necessarily coupled to the Infrastructure.

Now suppose that, when something happens in the system, we want to notify the user or update a UI element.

Or using Uncle Bob’s terminology:

With this, we are back to his original diagram.

Let’s review how the flow of execution would go for an incoming HTTP request:

1. The Request reaches the Controller
2. The Controller:
   1. Dismantles the Request and creates a Request Model with the relevant data
   2. Through the Boundary, triggers the Interactor
3. The Interactor:
   1. Finds the relevant Entities through the Entity Gateway
   2. Orchestrates interactions between entities
   3. Creates a Response Model with the relevant data and sends it to the Presenter through the Boundary

The diagram in the lower right corner of the first image on the original post might help visualize what’s going on.

Swap ‘Use Case Output/Input Port’ for ‘Boundary’.