Hexagonal architecture - Another way to the hexagone

Source: Dev.to

Hexagonal

I first learned about Hexagonal Architecture (the term I’ll use from now on) in the Clean Architecture book — see the article “Clean Architecture”. It was inspired by Uncle Bob, who wanted to bring clean architecture into practice. Alistair Cockburn realized that there was a different approach to building applications than the classic 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 is to use the same code to process business rules. Although experts argue that there are differences between open and closed layers, the hexagonal approach aims to avoid such interactions by design rather than by enforcing a constraint.

Nevertheless, Stenber notes in his InfoQ blog post that Hexagonal Architecture can be seen as a form of layered architecture because it conforms to the same constraints and properties.

---

Hexagonal vs. Clean Architecture?

Hexagonal Architecture is often mentioned together with Clean Architecture. While Clean Architecture was inspired by the hexagonal style, the two are not identical.

• Valentina Cupác explains the differences in her talk. In my experience, many code bases mix the two, but Clean Architecture tends to be more prescriptive.
• Juan Manuel Garrido de Paz writes that the Ports & Adapters pattern “says nothing about the structure of the inside of the hexagon.” In other words, Ports & Adapters is simply another name for the same architectural style.

This seems to contradict Juan Manuel’s own statement that the pattern “says nothing about layers.” The problem is that “layer” is an abstract concept that can be interpreted differently, leading to confusion. The term “layer” may be too vague when communicating the idea.

---

Another Way to the Hexagon

Alistair Cockburn’s “hexagon” playlist on YouTube – DDD – FR — elaborates on his insights while developing and formalizing the architectural style that is widely known today. For curious readers, the videos explain the why behind the naming, the decisions, and the need that led Alistair to create the style.

---

Definition

Below is the diagram from the architectural‑style creator Alistair Cockburn:

Hexagonal Architecture can be described through a few key aspects, which together define the style:

• Ports – “The term ‘port and adapters’ picks up the purposes of the parts of the drawing. A port identifies a purposeful conversation.”
• Adapters – You may have many adapters for a single port.

In the book Strategic Monoliths and Microservices (see the section on hexagonal architecture), Vaughn Vernon and Tomasz Jaskula use a similar definition. Their description also highlights how the style differs from classic layered architecture.

Ports and Adapters deserve special attention:

• A driver adapter implements a driver port interface, translating requests from a specific technology into a technology‑agnostic format that the driver port can understand and process.
• Juan Manuel Garrido de Paz calls the interface that controls how to interact with the application Driver, and the interface that acts as an output boundary Driven.

---

A Note on the Implementation

In the implementation referenced later in this post, I use the terms inbound and outbound to name the interfaces that interact with the application. “Inbound” corresponds to driver ports (incoming requests), while “outbound” corresponds to driven ports (outgoing calls).

Inbound / Outbound

In hexagonal (ports‑and‑adapters) architecture the inbound side is the interface used to interact with the application, while the outbound side is the interface used to interact with external systems:

• inbound → Driver (e.g., CLI, GUI, REST API)
• outbound → Driven (e.g., database, message broker, any external system)

---

What are the disadvantages of hexagonal architecture?

At first glance hexagonal architecture looks like a magical approach that will automatically make any application testable. Some articles indeed promote it as a silver‑bullet for testability, but adopting it brings several implications:

In practice, the shift to hexagonal architecture is often driven by the team’s experience. As developers become more familiar with the pattern, the above concerns diminish.

---

Related subjects

• Gordon Skinner – Hexagonal Architecture in DDD (YouTube)
• Implementing Domain‑Driven Design by Vaughn Vernon – Chapter 4
• Software architecture patterns (Dev.to) (the original link was malformed; replace with a suitable article if needed)

---

References

• Stenber, J. (2014). Exploring the Hexagonal Architecture.
• Vernon, V. (2021). Strategic Monoliths and Microservices. Addison‑Wesley Signature Series.
• Vieira, D. (2021). Designing Hexagonal Architecture with Java: An architect’s guide to building maintainable and change‑tolerant applications with Java and Quarkus. Packt Publishing.

---

Hexagonal in practice

Problem statement

The number of people creating content for social media is growing, and so is the need for tools that automate daily tasks such as creating, scheduling, and publishing posts. Our tool, Social Publisher, addresses these needs.

Social Publisher

The example application is a command‑line tool written in Kotlin. Its core features are:

• Create posts (focus on the content)
• Delete posts
• Schedule posts for a specific date and time
• Send posts to social media (currently supports X.com)

The source code is available on GitHub.

Structure overview

The project is divided into application (business logic) and adapters (inbound/outbound). The naming follows Alistair Cockburn’s interpretation of the hexagonal architecture.

• Inbound adapters provide input to the application (in this case, only a CLI).
• Outbound adapters handle the output (CLI output and CSV persistence).

Directory layout

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
│           └── InMemorySchedulerRepos...

(The tree continues with the remaining files; truncated for brevity.)

---

Project Structure

itory.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

---

Testing Approach

Given an already defined architectural style, the testing strategy follows the same layered boundaries:

• Adapters – Tested in isolation. This isolates edge‑case behavior and keeps each test granular.
• Inbound adapters – Exercised through a CLI application (the entry point for the system).
• Outbound adapters – Also tested in isolation; they represent the components that communicate with external systems.
• End‑to‑end (e2e) tests – Run against the full stack using the adapters defined in the configuration layer.

“Nat Pryce depicts this in detail.” – see his article.