Hexagonal architecture - Another way to the hexagone

Last updated Jan 4, 2025 Published Apr 13, 2022

The content here is under the Attribution 4.0 International (CC BY 4.0) license

Theory

Hexagonal Architecture, also known as the Ports and Adapters pattern, offers a powerful way to design software systems that are modular, testable, and adaptable to change. This architectural style emphasizes the separation of concerns, ensuring that core business logic remains independent of external systems such as databases, user interfaces, or third-party services.

In this blog post, we’ll explore Hexagonal Architecture in two parts. The first part dives into the theory, explaining its principles, benefits, and how it contrasts with traditional layered architectures. The second part brings these concepts to life with a real-world implementation based on my interpretation of Hexagonal Architecture, demonstrating how to structure code for flexibility and maintainability.

Hexagonal

I got to know hex architecture(I am going to follow this pattern from now on to refer to the hexagonal architecture) in the clean architecture book, indeed it was inspired by Uncle Bob to get the clean architecture in place. Alistair Cockburn realized that there was a different approach to building applications instead of the classical layered architecture:

The attempted solution, repeated in many organizations, is to create a new layer in the architecture, with the promise that this time, really and truly, no business logic will be put into the new layer.

A more flexible way of dealing with different adapters in the application and using the same code to process business rules. Even though experts argue that there are differences between open and closed layers, to avoid such interactions or constraint violations, in the hex architecture the approach is different stating that the goal is to avoid it by design instead of trying to enforce a constraint. Nevertheless, Stenber in his blog written for infoQ says that hexagonal architecture is an example of a layered architecture as it conforms to all the constraints and properties of a layered architecture [1].

Hexagonal vs Clean Architecture?

Hexagonal architecture is usually mixed with clean architecture, even though, it was used as an inspiration for the clean architecture, they are different. Valentina Cupác describes that in her talk with details.

Another way to the hexagone

Definition

Let’s start with the diagram from the architectural style creator Alistair Cockburn that has this image in his blog post:

Diagram representing the hexagonal architecture

Hexagonal architecture is defined in different aspects. Aspects are something that created to define this architectural style as I believe they are the key:

  • ports, as the author describes “The term “port and adapters” picks up the ‘’purposes’’ of the parts of the drawing. A port identifies a purposeful conversation”.
  • adapters, you might have many adapters for a single port.

In the book Strategic Monoliths and Microservices [2] Vaughn Vernon and Tomasz Jaskula also used a similar definition, on the other hand, what caught my attention to their definition is the way used to differentiate the layered architecture from hexagonal.

What are the disadvantages of hexagonal architecture?

At first, the hexagonal architecture seems to be a magical approach that will automagically give testability to any application, at least this is what some of the articles on the web sells the hexagonal architecture. Nevertheless, some of the implications that come when adopting hexagonal architecture are:

  1. The developer experience: as the implementation of hexagonal architecture depends on interpretation, it varies based on the programming language and the years of experience of the developer writing the code. Hexagonal architecture usually is not the first style that one starts with. It is MVC that comes embedded in different frameworks.
  2. The understanding of the developer on the libraries and the frameworks being used: the different ecosystems of different programming languages bring challenges as they offer a pre-created structure of how the problem should be solved. Understanding each piece of them is key to creating abstraction to create the inside and the outside of the hexagon. For example, Davi Vieira shared his opinions on implementing hexagonal architecture with Java in a book [3].
  3. Other architectural styles are also testable: other styles are posed as “not testable” or that are difficult to test, regardless, frameworks are set to use the famous Model-View-Controller.

Being said that the shift using hex architecture is mostly due to the developer experience at hand. Having experience, the other points mentioned will degrade their impact.

References

  1. [1]J. Stenber, “Exploring the Hexagonal Architecture,” 2014 [Online]. Available at: https://www.infoq.com/news/2014/10/exploring-hexagonal-architecture. [Accessed: 15-Apr-2022]
  2. [2]T. J. Vaughn Vernon, Strategic Monoliths and Microservices. The Addison-Wesley Signature Series, 2021.
  3. [3]D. Vieira, Designing Hexagonal Architecture with Java: An architect’s guide to building maintainable and change-tolerant applications with Java and Quarkus. Packt Publishing, 2021.

Hexagonal in practice

Let’s dive into the implementaion of this architetural style to translate the theory into concrete implementation. We will do that through a fiticious application that is used for scheduling posts in social media.

Problem statemenet

Given the number of people that are genearing content for social media and making it a business is increasing, the need for automated tools to support the day to day work oif those people also increase. Creating, Scheduling and Sending the content to those platforms are one of the focus os social publisher.

Social publisher

To depict what I have implemented thinking about hexagonal architecture we will use this made up business that aims at posting content into social media, currently the application is used through the Command Line Interface and it was built using kotlin. Let’s dive into the features:

  • Create posts and focus on the content
  • Delete posts
  • Schedule posts to be sent based on a date and time
  • Send posts to social media (X.com is supported for the time being)

The source code for social publisher is available on GitHub.

Structure overview

The packages of the application were split into application and adapters, the aim was to be strict with the naming from the image and explanation from Aliastair in his interpretation of the architecture. The application has all the business logic needed to fulfill the requirements of scheduling and posting. The adapters on the other hand, was split into two, the inboud and the outbound. The idea is as follows:

Package diagram representing the hexagonal architecture

Inbound are the adaptares that offers input to the application, in this case it is only the CLI, and outbound represents the output that the application writes to, in this case the CLI as well as storing the data in CSV.

src/main/kotlin/
├── Main.kt
├── adapters
│   ├── inbound
│   │   └── cli
│   │       ├── CliFactory.kt
│   │       ├── Configuration.kt
│   │       ├── Post.kt
│   │       ├── Poster.kt
│   │       └── scheduler
│   │           ├── Scheduler.kt
│   │           ├── SchedulerCreate.kt
│   │           ├── SchedulerDelete.kt
│   │           └── SchedulerList.kt
│   └── outbound
│       ├── cli
│       │   └── CliOutput.kt
│       ├── csv
│       │   ├── FileSystemConfigurationRepository.kt
│       │   ├── FileSystemPostRepository.kt
│       │   └── FileSystemSchedulerRepository.kt
│       ├── inmemory
│       │   ├── ConfigurationInMemoryRepository.kt
│       │   ├── InMemoryPostRepository.kt
│       │   └── InMemorySchedulerRepository.kt
│       └── social
│           ├── CouldNotCreateTweetException.kt
│           ├── CreateTweet.kt
│           ├── DeleteTweet.kt
│           └── TwitterCredentialsValidator.kt
└── application
    ├── Messages.kt
    ├── Output.kt
    ├── configuration
    │   ├── ConfigurationGivenHasInvalidProperty.kt
    │   ├── Create.kt
    │   └── List.kt
    ├── entities
    │   ├── ScheduledItem.kt
    │   ├── SocialConfiguration.kt
    │   └── SocialPosts.kt
    ├── persistence
    │   ├── PostsRepository.kt
    │   ├── SchedulerRepository.kt
    │   └── configuration
    │       ├── ConfigurationRepository.kt
    │       └── MissingConfiguration.kt
    ├── post
    │   ├── Create.kt
    │   └── List.kt
    ├── poster
    │   └── Executor.kt
    ├── scheduler
    │   ├── Create.kt
    │   ├── List.kt
    │   ├── SocialMedia.kt
    │   └── filters
    │       ├── Criterion.kt
    │       ├── DateTimeValidation.kt
    │       ├── StartDate.kt
    │       └── UntilDate.kt
    └── socialnetwork
        ├── CreateTweet.kt
        ├── DeleteTweet.kt
        ├── MissingConfigurationSetup.kt
        └── SocialThirdParty.kt

You also might like

Made with 💖 by @MatheusMarabesi