Site Reliability Engineer, Software Engineer, coffee addicted, traveler

Hexagonal Architecture x Onion Architecture x Clean Architecture: their differences

May 8, 2023


Share it

Hexagonal Architecture

I bet you have heard about this one, for sure. If not just google something like how to build an API with hexagonal architecture and you'll see a plenty of tutorials, examples and Github repositories showing some examples. And I also bet that the majority of them will not explain why it has such name.

Hexagonal archictecture has nothing to do with hexagons. A better name for it would be the one that its author gave it: Ports and Adapters. This pattern was proposed by Alistair Cockburn and the original publication is avaiable on his blog.

The main ideia of it is to protect the core product source code from changes on external dependencies, such as database (for sure we can discuss how frequently we change database during projects, but on other article latter on). To do so, the basic idea is: every time we detect that something is not part of the system per se we add an abstraction for it (a port), in OOP languages it might be an interface, and then we create a concrete implementation of such abstraction, and we name this implementation adapter, which could be a class that implements that interface and is injected into the code.

Just to give you a simple and minimalist example to think about, consider a system that needs to perform queries against a database, read and write data on a cache, and fetch some data from a CMS. For each one of these needs, you could create interfaces describing how they should behave. That way, you could forget about database-specific configs, for example, and focus on coding what you need. Suppose you decide to use Postgres for production and SQLite for local development. In that case, you could create one class for each of these databases, implementing the contract established by the interface. This approach allows your application to be more flexible and maintainable in the long run.

Onion Architecture

Onion Architecture was proposed by Jeffrey Palermo and you can check the original article on his blog. It extends the ideia of protecting the system's core from the Hexagonal Architecture by introducing layers surrounding it. This core is named domain model and it must define business rules and invariants.

On top of the core we create the domain services layer which adds objects that supports enterprise services and add business rules that don't fit well into the domain model, like validations that requires some database interaction.

Wrapping the domain services layer we have the application services layer, which coordenates execution flows like a request hitting a controller what needs to call a domain-service to perform some action.

Clean Architecture

Clean Architecture was proposed by our dear Uncle Bob and you can check the original article on his blog. Summarizing, it extends the Onion Archiecture and the key difference is that domain model in this contexts is called entity and application service is called use case, which is good because it gives more visibility about what the application in fact does.


All three ideas above proposes the same thing: decouple the business rules from the framework and infrastructure-specific code, arguing that it'll make the application flexible and maintainable in the long run.