Tech & Engineering
min of reading
August 27, 2020

Use of the Hexagonal Architecture Pattern

Morvana Bonin
Backend Software Engineer with a strong passion for design patterns, clean code and software architecture.
More about the author

With the emergence and growing adoption of Microservice Architecture, the demand for architectural patterns that can help to create and implement these services also grows.An architectural pattern can provide great help in this journey of creating and implementing services. The goal of this post is to present the Hexagonal architectural pattern, its advantages and some disadvantages, and how to use it.It is important to remember that every choice has a cost. So, it is worth mentioning that it is recommended to learn about several tools, their advantages, and costs, and choose the one that is most cost-effective considering the advantages.

Hexagonal Architecture Pattern

There is a phrase that I heard once related to life, but it also applies to software development:

"An immature person thinks that all his choices generate gains... a mature person knows that all choices have losses." (Augusto Cury)

In general, the more tools you know and the more information you have about their advantages and costs, you tend to make a better choice of which tool to use as a solution according to the challenge presented.Well, let's understand the Hexagonal Architecture pattern.

Create your application to work without an UI or database, to which you can run automated regression tests, implement when the database is not available and connect applications without involving them. (Alistair Cockburn)

This is how the post begins, extracted from the documentation on the website of Alistair Cockburn, creator of the Hexagonal Architecture pattern or even known as the pattern of doors and adapters.

One of the reasons for creating this pattern was mainly to delegate the infrastructure and UI part of the project, focus on the business rule and make it functional, in addition to not mixing it up, that is, a business rule in the database or even in the UI part of a project.

Hexagonal architecture is shared into 3 parts:

  • Hexagon center
  • Left side of the hexagon
  • Right side of the hexagon

In this scenario, we have the actors that will interact with the center of the hexagon:

  • The primary actor, who will lead an action;
  • The secondary actor to be led.

A common question is the difference between the actors: who are the primary actors in my application? Who are the secondary actors?

To answer this question, it is necessary to ask another question:

"Who starts the conversation?

"That is, who is responsible for starting the flow, the actor who performs an action?

When answering this question, you will have the primary actors, no matter if it is a person, another system, a bash script that calls your adapter, if it fires a trigger that calls the core business of your application. It is the primary actor.

Then, the secondary actor will be led to perform a certain action that the primary actor has triggered. It can be recording data, logging them, or even calling a third application and getting a response, returning to the primary actor.

The center of the hexagon

It is where the models, domains and business rules of your software are located. It is an environment that must be totally isolated in terms of not being affected by external occurrences, for example, the database that will be used, the frontend framework.

Left side of the hexagon

It is the primary actor side, user-side, that conducts an action, as this is the side of the user who performs some task.

Right side of the hexagon

It is the side of the secondary actor, data-side, that is conducted, whether to write data, read data, modify data, and delete data.


Doors are the communication gateway between the center of your hexagon with the left and right sides of your hexagon, with the external sides.


Adapters are the users of the doors. For each door that your hexagon has, an adapter must be created, hence, you have the freedom to modify and delete it dynamically.In doors and adapters, we also have the concept of primary and secondary doors, and the concept is the same used with the actors.

In the primary actors of our application we have the conductors of the action, that will use the primary adapters, and this will “knock” on the primary doors. So, the secondary doors and adapters will drive the action to the secondary actor in the continuous flow of the application.

Inversion of Control (IoC)

In a real flow, using as an example the simple recording of data, we would have the following:

  • The left side (the driver) delivers the information, using an adapter and through the primary door, to the center of the hexagon (domain).
  • The center of the hexagon, then, receives data through the door, then processes them using a secondary door and calls the right side.
  • The right side (the entity led) calls a database to record them.

In the end, we would have this as the Hexagon flow:

Left side -> Center -> Right side

But this scenario impacts the concepts of Hexagonal Architecture, which is that the domain must be isolated and responsible only for the business rule, because in the example above, it would have to be responsible for calling the entity responsible for recording.

Now, the concept of Inversion of Control (IoC) emerges.

Inversion of Control (IoC) is a pattern that advocates to use instances of a certain class, treating it externally and not within the class in question, that means, delegating control from one class to another. It can be an interface, component, service, etc.

In our case, it will reverse precisely the flow order, making sure that, still using the example, our database goes to our center and not the other way, leaving our domain really isolated.

In the end, this would be our correct flow:

Left side -> Center <- Ioc- Right side


As strengths of using this architecture, we can list:

  • Independent External Services Solution
  • Enables postponing some technical decisions
  • Creation and replacement of adapters
  • Easy to test the application
  • Easy to exchange technologies


We also have some negative aspects in the use of this hexagonal architecture, which are:

  • Additional complexity (building more layers)
  • Creation and maintenance cost
  • There is no guidance on organizing code (directories, layers)


The hexagonal architecture is taken as a guide, and from it, new architectural concepts were created with more granular information in the code organization (directories, layers), as examples we have the Onion Architecture, by Jeffrey Palermo, and the Clear Architecture, by Robert C. Martin (Uncle Bob). Both refer to the pattern created by Alistair Cockburn.

Even if you already have chosen to follow the idea of Jeffrey or Uncle Bob, I recommend studying the hexagonal architecture to understand the concept of isolation of the domain and communication with its respective actors. After that, you will see that it will become easier to understand the ideas of other authors who created new concepts based on that initial idea.

subscribe to our newsletter with exclusive content.

Click and join the Sensedia News!

Click and join the Sensedia News!

Click and join the Sensedia News!

Thanks for reading!