---
description: A Craftsman's Guide to Software Structure and Design
---

# Clean Architecture

## Connection

* Split the group in 4 :
* Ask this question
  * What characteristics do these architectures have in common? - 5'
  * Craft as many post-its as they can
* Review what has been produced

#### Hexagonal architecture

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBm5SHAQNSPhXT1tUUk%2F-MBmGI3OreGzXugbMmtM%2Fimage.png?alt=media\&token=58e3d2c8-549c-4e14-a288-07eb9f008e8d)

![Alistair Cockburn](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBm5SHAQNSPhXT1tUUk%2F-MBmKntsiSt4Im6vvP2e%2Fimage.png?alt=media\&token=833df56f-2b57-429a-a92c-ade07100066c)

#### Onion architecture

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBm5SHAQNSPhXT1tUUk%2F-MBmLaZJ9xuAduCfeImo%2Fimage.png?alt=media\&token=566682db-3b47-42cb-b79d-c575e84d11bb)

![Jeffrey Palermo](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBm5SHAQNSPhXT1tUUk%2F-MBmLe2ZMeA1aXrmHfgW%2Fimage.png?alt=media\&token=adbc860c-cc67-42cb-b21e-40893bf51e6a)

## Concepts

### Hexagonal Architecture

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBm5SHAQNSPhXT1tUUk%2F-MBmMBWiBDooLipo0hns%2Fimage.png?alt=media\&token=cab71e80-11fc-4dc4-8b55-929f8e5c3413)

{% hint style="info" %}
_Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases._
{% endhint %}

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBm5SHAQNSPhXT1tUUk%2F-MBmMHM-PBPorzUve971%2Fimage.png?alt=media\&token=294e45c7-1bc1-47bb-b812-451e7f9d1adb)

Source : [https://blog.octo.com/architecture-hexagonale-trois-principes-et-un-exemple-dimplementation/](https://blog.octo.com/architecture-hexagonale-trois-principes-et-un-exemple-dimplementation/)

### Onion Architecture

#### Layers

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBm5SHAQNSPhXT1tUUk%2F-MBmMrvuxP8NznMVQgcQ%2Fimage.png?alt=media\&token=2e17516c-ec5f-4f32-ad05-310e766f3ead)

* _**Domain Model layer**_, where our entities and classes closely related to them e.g. value objects reside
* _**Domain Services layer**_, where domain-defined processes reside
* _**Application Services layer**_, where application-specific logic i.e. our use cases reside
* _**Outer layer**_, which keeps peripheral concerns like UI, databases or tests

#### Dependency Inversion Principle (at Architecture Level)

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBm5SHAQNSPhXT1tUUk%2F-MBmN_WMNqNN1LSiatby%2Fimage.png?alt=media\&token=7843de67-b9d3-4a55-b383-ef6fa84e068f)

This means that when writing our high-level business logic, we don’t want to depend directly on low-level stuff like databases, file systems, network connections, provider contracts, and such.

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBm5SHAQNSPhXT1tUUk%2F-MBmOBDmOG1XnOvjih9l%2Fimage.png?alt=media\&token=8089aa11-b446-4661-b556-5dcb6c69b9b1)

{% hint style="success" %}
_Instead, we should expose an abstraction that represents a higher-level business need and implements it using these low-level mechanisms._
{% endhint %}

### What characteristics do these architectures have in common?

Here is some answers to the connection question :

* Independent of frameworks
  * Does not depend on the existence of libraries
  * Allow us to use frameworks as tools (not a constraint)
* Independent of the front-end
  * Can easily change the UI (from web to console)
* Independent of the database
  * Business rules not bound to Database logic
* Independent of any external agency
  * Business rules don’t know anything about outside world

{% hint style="success" %}
_**Business rules can be tested without external components**_
{% endhint %}

### Use Case Driven Approach

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBmQ613EJWmDh4FUe6F%2F-MBmR-pxOQY_fYY8MMgR%2Fimage.png?alt=media\&token=8d099a17-0f88-4858-9f5d-5395bd9cb4bc)

Ivar Jacobson in his book below explained we should map 1 Business Use case / 1 Application Use case. We should implement Application Use Case with the BCE "pattern" : Boundary Controller Entity :

![BCE](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBmQ613EJWmDh4FUe6F%2F-MBmRptAqqjnvRm2OqjM%2Fimage.png?alt=media\&token=14c7a5f2-8fde-4ccd-abdb-fa66bd7e3932)

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBmQ613EJWmDh4FUe6F%2F-MBmR7zaLLaxnXQFd6Qe%2Fimage.png?alt=media\&token=254cf09d-aac6-48b3-8f0f-dee77d050ca2)

### Clean Architecture

![Uncle Bob's book](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBmWY8j2bULNl3viPPS%2F-MBmXp8yL4EdnrGHuqUl%2Fimage.png?alt=media\&token=490799a2-bc19-4131-879b-759c2cffedb4)

The Clean Architecture as expressed by Robert C. Martin is a mix of the 3 architecture ideas explained before :

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBmS7EO8Fe7VVZVRc_Q%2F-MBmS9tX9OP1kMC9I4z6%2Fimage.png?alt=media\&token=5aff66d7-0528-45ba-95d3-003b2b824ca0)

#### Entities (Enterprise business rules)

* Encapsulate Enterprise wide business rules
  * Can be
    * Object with methods
    * Set of data structures and functions&#x20;
* Could be used by many different applications in the enterprise.

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBmS7EO8Fe7VVZVRc_Q%2F-MBmSUTaYtkmeknpwB6O%2Fimage.png?alt=media\&token=1e2de086-60ea-4a35-a04a-5ef7d06fdab9)

#### Use cases (Application business rules)

* Capture business rules&#x20;
* Structure should indicate what the application is, not how it does it&#x20;
* Application specific business rules

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBmS7EO8Fe7VVZVRc_Q%2F-MBmSlD6KWJUvhsJ8Qn5%2Fimage.png?alt=media\&token=c199915a-d1c9-44c2-869d-e29c51907a30)

#### Interface adapters

* Set of adapters
  * Convert data from the format most convenient for the use cases and entities
  * To the format most convenient for some external agency such as the Database or the Web&#x20;
* In a MVC architecture : Presenters, Views, and Controllers

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBmS7EO8Fe7VVZVRc_Q%2F-MBmSymFA7SXW5X2vzL8%2Fimage.png?alt=media\&token=68a86aba-73a4-458a-ab23-66bed34ab875)

#### Frameworks & drivers

* Frameworks and tools such as
  * Database
  * Web Framework

{% hint style="info" %}
_Glue code that communicates to the next circle inwards._
{% endhint %}

* This layer is where all the details go
  * Keep these things on the outside where they can do little harm

#### The dependency rule

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBmTOBnXpF9UBAUZ6mr%2F-MBmTc95yWDUAdCVt6hL%2Fimage.png?alt=media\&token=0e72d8a3-a4ce-4979-a236-c88e52fb12a8)

{% hint style="success" %}
Source code dependencies can only point inwards.
{% endhint %}

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBmTOBnXpF9UBAUZ6mr%2F-MBmThSYwcS6aIJOExjz%2Fimage.png?alt=media\&token=7efcc924-32d6-445d-b075-ea20d0b3c140)

## Concrete Practice

* Clone the repository at : [https://github.com/ivanpaulovich/clean-architecture-kata-dojo](https://github.com/ivanpaulovich/clean-architecture-kata-dojo)
* Checkout the branch “kata-initial”

### Objective

Learn and practice the concepts behind Clean Architecture

### Part 1

Each participant :

* Position projects on the Clean Architecture Diagram
* Draw the sequence diagram of the Register Use Case
  * They can use :
    * [https://sequencediagram.org/      ](https://sequencediagram.org/)
    * [https://plantuml.com/](https://plantuml.com/)
    * [https://app.diagrams.net/](https://app.diagrams.net/)

![Empty Clean architecture Diagram](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBmUN-RX3ydc58iFHLS%2F-MBmUYIwDoSnZVsMIXwW%2Fimage.png?alt=media\&token=e892767b-7918-4392-bba3-4887e77395d2)

#### Correction

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBmUN-RX3ydc58iFHLS%2F-MBmV-4aKfM5LP_oHgSq%2Fimage.png?alt=media\&token=e2e82c9c-8e0c-4b4a-b127-9b1bc9ad97ec)

![Register User Case](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBmUN-RX3ydc58iFHLS%2F-MBmVqDnpmAe54_ZXA8q%2Fimage.png?alt=media\&token=e78df586-6df3-4fe3-b180-a54d027d845f)

### Part 2

Cover the following use cases and requirements:

* The customer can register a new account.&#x20;
* Allow to get the customer details.&#x20;
* Allow to get the account details.&#x20;
* Allow to deposit into an existing account.&#x20;
* Allow to withdraw from an existing account.&#x20;
* Accounts can be closed only if they have zero balance.&#x20;
* Accounts does not allow to withdraw more than the current account balance.

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBmUN-RX3ydc58iFHLS%2F-MBmWMDzvbIEPg_IYu76%2Fimage.png?alt=media\&token=4001717e-4417-4965-b27f-18bec1b35611)

You can check in the branch **final-solution** to see one possible implementation of those Use Cases

## Conclusion

* What benefits do you see?&#x20;
* Pros and cons ?

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MBmWY8j2bULNl3viPPS%2F-MBmX5VAZoSOusvvp33k%2Fimage.png?alt=media\&token=114dc11e-1b83-4ac3-b6f8-e0b96b802770)

### Pros & Cons

| Pros                                                                                                                                       | Cons                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| _**Plays well with DDD**_ – architecture that builds everything on top of a domain model                                                   | _**Learning curve**_ – People tend to mess up splitting responsibilities between layers, especially harming the domain model |
| _**Directed coupling**_ – the most important code in our application depends on nothing, everything depends on it                          | _**Indirection**_ – interfaces everywhere!                                                                                   |
| _**Flexibility**_ – from an inner-layer perspective, you can swap out anything in any of the outer layers and things should work just fine | _**Potentially heavy**_                                                                                                      |
| _**Testability**_ – since your application core does not depend on anything else, it can be easily and quickly tested in isolation         |                                                                                                                              |

## Support

{% embed url="https://speakerdeck.com/thirion/clean-architecture-hands-on?slide=1" %}

## Resources

* Hexagonal Architecture : [https://blog.octo.com/architecture-hexagonale-trois-principes-et-un-exemple-dimplementation/](https://blog.octo.com/architecture-hexagonale-trois-principes-et-un-exemple-dimplementation/)
* Onion Architecture : [https://bitbucket.org/jeffreypalermo/onion-architecture/src](https://bitbucket.org/jeffreypalermo/onion-architecture/src)
* Clean Architecture : [https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
* A simple template for Onion Architecture with .NET 5 : [https://pereiren.medium.com/a-simple-template-for-onion-architecture-with-net-5-6c0e2f3b29c8](https://pereiren.medium.com/a-simple-template-for-onion-architecture-with-net-5-6c0e2f3b29c8)

![](https://1936518372-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MAffO8xa1ZWmgZvfeK2%2F-MToGJMEt7x-fDpfIaio%2F-MToH9SZ3vfvnqCWEvV6%2Fimage.png?alt=media\&token=faf750a5-8a8a-4c7b-b046-207924d888b4)

