Clean architecture series — Part 3
Tags: architecture, career, design, productivity
Published: 2020-04-20 07:11:40

“ Anxiety arises from not being able to see the whole picture. If you feel anxious but you are not sure why, try putting your things in order.” — Marie Kondo

![](https://cdn-images-1.medium.com/max/1024/1*9_xIZvlpZ2ZrMp-LdrrUkA.png)

### The Clean Architecture 🧹

We **have seen what Hexagonal and Onion Architectures are** , so the **next step** is to review what **Clean Architecture means**.

> You can check the first two articles about Hexagonal and Onion architectures here:

- [Clean architecture series— Part 1](https://dev.to/pereiren/clean-architecture-series-part-1-m64)
- [Clean architecture series — Part 2](https://dev.to/pereiren/clean-architecture-series-part-2-49db)

### What is Clean Architecture?

Architecture pattern [promoted by Robert C. Martin (Uncle Bob) in 2012](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) trying to do one more step in architecture patterns when thinking about isolated, maintainable, testable, scalable, evolutive and well-written code. Following similar principles to Hexagonal and Onion, Uncle Bob presented his architecture together with this diagram:

![](https://cdn-images-1.medium.com/max/772/0*4SYfkCc1p5Z62psJ.jpg)<figcaption><a href="https://blog.cleancoder.com/uncle-bob/images/2012-08-13-the-clean-architecture/CleanArchitecture.jpg">https://blog.cleancoder.com/uncle-bob/images/2012-08-13-the-clean-architecture/CleanArchitecture.jpg</a></figcaption>

The **main goal of this architecture is the separation of concerns**. Uncle Bob mentioned that **he didn’t want to create another new and totally different architecture from Hexagonal and Onion**. In fact, he did want to integrate **all of these great architectures into a single actionable idea**.

The key principles of this architecture are:

- It’s really about the **Separation of Concerns**
- Should be **independent of frameworks**
- They should be  **testable**
- They should be **independent of a UI**
- They should be **independent of a database**
- The **Clean Architecture Diagram**  
 —  **Innermost** : “Enterprise / Critical Business Rules” ( **Entities** )  
 —  **Next out** : “Application business rules” ( **Use Cases** )  
 —  **Next out** : “Interface adapters” ( **Gateways, Controllers, Presenters** )  
 —  **Outer** : “Frameworks and drivers” ( **Devices, Web, UI, External Interfaces, DB** )
- The **innermost circle** is the most general/ **highest level**
- **Inner circles are policies**
- **Outer circles are mechanisms**
- **Inner circles cannot depend on outer circles**
- **Outer circles cannot influence inner circles**

So yes, these principles are coming from Hexagonal and Onion architectures as you must be wondering right now.

Also, all of these principles are following the same rule, which is…

### The Dependency Rule

The concentric circles represent different areas of software. In general, **the further in you go, the higher level the software becomes. The outer circles are mechanisms. The inner circles are policies.**

#### What does that mean?

**Nothing in an inner circle can know anything at all about something in an outer circle**. In particular, the **name of something declared in an outer circle must not be mentioned by the code in an inner circle**. That includes functions, classes. variables, or any other named software entity.

**_For example:_**

**Elements located in the Entities circle** (the enterprise business rules) **should not refer to any elements outside of it** (such as application business rules, interface adapters, frameworks, and drivers).

**Data formats used in an outer circle should never be used by an inner circle** , especially if they are generated by a framework in an outer circle. The Clean Architecture prevents anything in an outer circle to impact the inner circles as shown in the following diagram:

![](https://cdn-images-1.medium.com/max/1024/0*00xx3fNwcNgsI1eV.png)

With that in mind already, let’s take a look at the defined circles in the diagram

### Circles of the Clean Architecture

![](https://cdn-images-1.medium.com/max/772/0*bQfITslYN44TZOGz.jpg)<figcaption><a href="https://www.codingblocks.net/wp-content/uploads/2018/02/The-Clean-Architecture-Cone.jpg">https://www.codingblocks.net/wp-content/uploads/2018/02/The-Clean-Architecture-Cone.jpg</a></figcaption>

#### Entities

- Entities encapsulate _Enterprise-wide_ business rules.
- An entity can be an object with methods, or it can be a set of data structures and functions. It doesn’t matter so long as the entities could be used by many different applications in the enterprise.
- If you don’t have an enterprise and are just writing a single application, then these entities are the business objects of the application. They encapsulate the most general and high-level rules.

#### Use Cases

- Use cases are application-specific business rules. Changes should not impact the Entities. Changes should not be impacted by infrastructure such as a database
- The use cases orchestrate the flow of data in/out of the Entities and direct the Entities to use their Critical Business Rules to achieve the use case.

#### Interface Adapters

- Converts data from data layers to use case or entity layers. Presenters, views, and controllers belong here.
- No code further in (use cases, entities) should have any knowledge of the database.

#### Frameworks and Drivers

- These are the glue that hooks the various layers up.
- The infrastructure details live here.
- You’re not writing much of this code, i.e. we use SQL Server driver, but we don’t write it.

**You can add as many circles as you need. These are schematic.** As Uncle Bob mentioned, you can have all the circles/layers you need **but following always The Dependency Rule**.

So the thing is, we have these circles and we follow The Dependency Rule, **but how am I supposed to cross these circles boundaries?**

### **How to cross Circle Boundaries?**

![](https://cdn-images-1.medium.com/max/229/0*eujwXuAal-vhAHPT.png)

**This little screenshot which is part of the original diagram** proposed by Uncle Bob **shows an example of how the Controllers and Presenters communicate with the Use Case in the next circle/layer.**

**The flow of control begins at the controller, moves through the use case, and then winds up executing the presenter.**

So if you remember well, **The Dependency Rule says that no name in an outer circle can be mentioned by an inner circle.** And following the Flow of Control, the Use Case needs to call the presenter. **And how do we solve that without violating The Dependency Rule? Two ways to handle it**

- **By using the Dependency Inversion Principle from SOLID principles** , where we can define a port (an interface) in the inner circle and implement it in the outer circle.
- **By using a great design pattern, Mediator.** By using it we can define an object that encapsulates how a set of objects interact.

From my point of view, **I prefer to use the Mediator pattern**. It has **two great benefits** that fit really well with the Clean Architecture:

- **Objects delegate their interaction to a mediator object** instead of interacting with each other directly.
- **It should be possible to change the interaction between a set of objects independently.**

![](https://cdn-images-1.medium.com/max/1024/0*G5S6qta2TmZHDRcG.png)

#### Presenters

This is another concept we can see in the Flow of Control diagram. **The purpose of the presenter is to decouple the use cases from the format of the UI.**

**They were created to decouple the interactor and the view, so if we use them we can follow the Dependency Rule.** If we were returning the response model for the API from the interactor we would be coupling an inner layer to the outer one and we wouldn’t be following the Dependency Rule.

### **Clean + Hexagonal + Onion Architecture**

In the **previous example on how to handle communication between Controllers and Use Cases we have seen how the Clean Architecture uses Ports and Adapters pattern**. Also remembering **if we bring back the key principles of the Onion Architecture we must remember that it is an architecture driven by use cases.** So with these **Use Cases we are introducing the usage of Onion Architecture principles**.

This is double confirming what I mentioned at the beginning of this article. **Clean, Hexagonal and Onion architectures are not competing with each other to see which one is cooler or better.**  **All** of them **try to find a way to separate concerns** , and **Clean Architecture is focused on combining principles from previous architectures patterns and** more principles (like **the** [**Stable Dependencies Principe**](https://ericbackhage.net/clean-code/the-stable-dependencies-principle/) **,** [**Stable Abstractions Principle**](https://ericbackhage.net/clean-code/the-stable-abstractions-principle/) **, SOLID, etc** )

#### So, how should I structure my code following all of this?

First of all, **this is not a dogma**. Benefits are known and it should be a 100% fit for a lot of enterprise projects where business rules change continuously and also we are adding more and more features. But maybe you don’t need to do this for a simple background process service or serverless function. It’s up to you.

But if you definitely want to try it, go for it. **Try to put everything in place understanding all the concepts and why you should put something in that circle/layer. And once you’ve tried it, compare your boilerplate with other clean architectures projects out there on GitHub** or wherever.

Next chapter will be focused on building an API following this architecture, but right now I would like to share the boilerplate of that API:

{% gist https://gist.github.com/pereiren/ed91e24d521f467802ddfac1ad4042c2 %}

This a simple version of the layers and folders structure for an API, **sometimes you need to use more architecture patterns, sometimes less. The important thing about this kind of stuff is understanding the rules and growing every day learning new things.**

### Conclusion

I think that **every day more and more developers try to understand how to create quality code following best practices** to add more features, to get good code coverage in the tests, to scale it up easily and **to maintain the code free of bugs and bad spaghetti code smells.**   
I have seen dozens of **legacy projects almost impossible to maintain, with a lot of bugs and bad practices generating performance issues, never-ending feature developments, and developers burnouts**.

![](https://cdn-images-1.medium.com/max/670/0*Gf_by7SlV2VEYfq_.jpg)<figcaption><a href="https://static.makeuseof.com/wp-content/uploads/2015/02/programming-burnout-670x335.jpg">https://static.makeuseof.com/wp-content/uploads/2015/02/programming-burnout-670x335.jpg</a></figcaption>

Clean Architecture pattern has become more popular in Android development during the past few years and I do really wish that it become more popular in backend architectures or even in the frontend.

Imagine the **satisfaction** of building something great each day, **creating well-engineered solutions for complex business scenarios** and making sure that you can add new features **without losing huge amounts of time and mental health.**

Of course, **some developers won’t like this thinking of creating clean code/architectures or they will say something like _“meh this looks over-engineered”._**

**I don’t like to reply to that** kind of comment. **But Marie Kondo does:**

> **There are two reasons we can’t let go: an attachment to the past or a fear for the future.**

![](https://cdn-images-1.medium.com/max/635/0*1JSUjnOfPJSQJ7Fd.jpg)

Remember to tidy up your code, she is watching you.

### The next article in the series will be more practical, building a simple API with .NET Core and accessing real data.

Also, if you enjoyed this article, **feel free to share it and to give some love!**

If you have read all of this, thank you very much. [Feel free to connect with me on Linkedin!](https://www.linkedin.com/in/davidpereirac/)

### **Repositories** following the Clean Architecture

- [https://github.com/android/architecture-samples/tree/todo-mvp-clean](https://github.com/android/architecture-samples/tree/todo-mvp-clean)
- [https://github.com/ivanpaulovich/clean-architecture-manga](https://github.com/ivanpaulovich/clean-architecture-manga)
- [https://github.com/bufferapp/android-clean-architecture-boilerplate](https://github.com/bufferapp/android-clean-architecture-boilerplate)
- [https://github.com/eduardomoroni/react-clean-architecture](https://github.com/eduardomoroni/react-clean-architecture)
- [https://github.com/jasontaylordev/CleanArchitecture](https://github.com/jasontaylordev/CleanArchitecture)
- [https://github.com/ardalis/CleanArchitecture](https://github.com/ardalis/CleanArchitecture)
- [https://github.com/carlphilipp/clean-architecture-example](https://github.com/carlphilipp/clean-architecture-example)

### References

- [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)
- [http://xurxodev.com/por-que-utilizo-clean-architecture-en-mis-proyectos/](http://xurxodev.com/por-que-utilizo-clean-architecture-en-mis-proyectos/)
- [http://jmperezramos.net/desarrollo-en-android/visteme-con-clean-architecture-que-tengo-prisas/](http://jmperezramos.net/desarrollo-en-android/visteme-con-clean-architecture-que-tengo-prisas/)
- [https://github.com/ivanpaulovich/clean-architecture-manga/wiki/Flow-of-Control](https://github.com/ivanpaulovich/clean-architecture-manga/wiki/Flow-of-Control)
- [https://herbertograca.com/2017/11/16/explicit-architecture-01-ddd-hexagonal-onion-clean-cqrs-how-i-put-it-all-together/](https://herbertograca.com/2017/11/16/explicit-architecture-01-ddd-hexagonal-onion-clean-cqrs-how-i-put-it-all-together/)
- [https://groups.google.com/forum/#!topic/clean-code-discussion/Ehwo7yIHUPQ](https://groups.google.com/forum/#!topic/clean-code-discussion/Ehwo7yIHUPQ)
- [https://vrgsoft.net/blog/clean-architecture-for-android/](https://vrgsoft.net/blog/clean-architecture-for-android/)