Hexagonal Architecture was first coined by Alistair Cockburn in 2005. It inspired similar architectures like the Onion Architecture or Uncle Bob's Clean Architecture. These architectures all have one thing in common. They separate domain code from infrastructure code. Learning hexagonal architecture may seem hard as there is much litterature on the subject, even though it comes down to this simple idea.


It has been said that hexagonal architecture is asymmetrical, that the dependencies on the left call the domain whereas the dependencies on the right are used by the domain.

The whole point of Hexagonal Architecture is to change perspective from a layered architecture. If the hexagon is in between two types of dependencies, it then resembles a lot a layered architecture.

In order to make this subteltly clearer, Alistair Cockburn renamed Hexagonal Architecture to ports and adapters. I personally don't like the name as it seems more technical and that hexagonal is easier to remember.

Structural changes

Hexagonal Architecture changes the way we structure an application, and how we test it. It is now possible to test only domain code, without loading cumbersome external dependencies. Of course this does not replace a good integration test, but since domain is isolated, tests are more precise: is it a domain error or am I loading a record from the database wrong ?

One thing to remember

These considerations are only side effects of the main rule of hexagonal architecture:

Separate domain and infrastructure code

In order to learn about hexagonal architecture, it's best to apply this rule and the rest will come naturally.