Hexagonal Architecture: principles, benefits and practical implementation

Hexagonal Architecture, also known as Ports and Adapters, is a software design approach that aims to create robust, maintainable and testable applications. Developed by Alistair Cockburn, this architecture addresses the modern challenges of software development, in particular growing complexity and the need to maintain high-quality code.

History and origins

Hexagonal Architecture was introduced by Alistair Cockburn to address the limitations of traditional architectures such as MVC (Model-View-Controller). Unlike those, Hexagonal Architecture offers a clear separation of concerns, isolating business logic from technical details.

Source of the diagram: What’s hexagonal architecture?

Core principles of Hexagonal Architecture

Separation of concerns

1. Domain: this layer contains the application’s core business logic. It is independent of the other layers and encapsulates all domain-specific rules and behaviours.
2. Application: the application layer orchestrates use cases and the interactions between the domain and the other components. It contains no business logic but calls the domain’s services.
3. Infrastructure: this layer handles technical details such as the database, external APIs, user interfaces, and so on. It contains the concrete implementations needed for the application to work.

Using ports and adapters

Ports define the interfaces (contracts) specifying the interactions between layers, while adapters implement those interfaces in order to isolate the components. This approach makes it possible to replace or modify components without affecting the rest of the application. In some projects, the terminology can be made more accessible — for example: Ports = contracts and Adapters = services or repositories.

Benefits of Hexagonal Architecture

1. Independence of business logic: the business logic is isolated from technical details, making changes and future developments easier.
2. Improved testability: tests can focus on specific components without depending on implementation details, which simplifies unit and integration testing.
3. Flexibility and scalability: the architecture makes it possible to add or replace components without impacting the rest of the system, offering great flexibility.
4. Better code organisation and understanding: the clear structure makes the code easier to read and maintain, making development more efficient.

Feedback from a consultant at Numendo

“Since 2022 I have been implementing Hexagonal Architecture on various projects, and this method has transformed the way I approach software design.” – Mehdi, Full Stack Lead Dev at Numendo. Here is in-depth feedback on the benefits and challenges this architecture brings, as well as the adaptations needed for effective implementation.

Understanding Hexagonal Architecture

Hexagonal Architecture, also known as Ports and Adapters, aims to create a clear separation between business logic and technical details. This approach makes it possible to keep the code clean, making it easier to test and maintain. The core of the application, representing the business logic, is surrounded by adapters that handle interactions with external systems such as databases or APIs.

Benefits

1. Separation of concerns: by isolating the business logic from technical aspects, the code becomes more modular and maintainable. It also allows for better project organisation and reduces the risk of technical layers seeping into the business logic.
2. Increased testability: components can be tested independently, which makes it possible to carry out more precise unit tests and ensure optimal code coverage. This reduces the risk of regressions and makes errors easier to pinpoint, whether the tests are manual or automated.
3. Flexibility and scalability: being able to replace external components without touching the core of the application makes updates and technology changes easier. This architecture makes it possible to start with a monolithic application and migrate to a microservices architecture if necessary.

Limitations

1. Initial complexity: implementing Hexagonal Architecture requires a good understanding of the underlying principles. For inexperienced developers, this complexity can be an obstacle, requiring appropriate training and initial support. At Numendo, every year we provide technical and practical training for our consultants in order to support them as their careers develop.
2. Verbosity and indirection: creating a large number of ports and adapters leads to a proliferation of files and can make navigating the code more complex. This calls for rigorous organisation and strict naming conventions in order to keep the project clear so that it can evolve over time without degrading its architecture.
3. Increased cognitive load: managing the various layers and levels of indirection can become mentally exhausting, especially in mixed teams where developers’ experience varies widely, or in large teams.

Practical adaptations

To make applying Hexagonal Architecture simpler, I have put several adaptations in place:

1. Clear internal standards: defining conventions specific to our team made it possible to simplify the architecture while retaining the key benefits. This includes consistent folder and file names and a well-defined project structure.
2. Rigorous unit tests: by isolating the different layers, we have been able to carry out more effective unit tests, thereby ensuring better code quality and early detection of errors.
3. Documentation and training: designing code that is largely self-documented, to which we add concise descriptions of how each building block works, together with the tests themselves, forms a complete documentation base. Regular training workshops have been essential in ensuring that every member of the team understands and correctly applies the principles of hexagonal architecture.

Despite its initial complexity, it offers a rigorous structure that makes applications easier to maintain and evolve over the long term. By adapting this architecture to our specific needs, we have managed to take advantage of its many benefits while minimising its drawbacks. This experience has not only improved the quality of our code, but also strengthened our ability to collaborate efficiently and in an organised way.

Resources and further reading

Key books

• Implementing Domain-Driven Design by Vaughn Vernon: an in-depth introduction to Domain-Driven Design and Hexagonal Architecture.
• Clean Architecture: A Craftsman’s Guide to Software Structure and Design by Robert C. Martin: details on Hexagonal Architecture and other software design practices.
• Domain-Driven Design: Tackling Complexity in the Heart of Software by Eric Evans: a classic on DDD that underpins the principles of Hexagonal Architecture.

Blog articles and online resources

• “Hexagonal Architecture” by Alistair Cockburn: the founding article on Hexagonal Architecture by its creator.
• “Ports and Adapters Architecture” by Herberto Graca: a comprehensive explanation of the Ports and Adapters architecture.

Talks and videos

• “Hexagonal Architecture” by Alistair Cockburn: a video presentation by the creator of Hexagonal Architecture.
• “Clean Architecture: Patterns, Practices, and Principles” by Uncle Bob (Robert C. Martin): a presentation of clean architecture principles, including concepts from Hexagonal Architecture.

Numendo experts

Mehdi, Full Stack Lead Dev at Numendo since June 2023, explains his vision of and approach to the method in his latest interview.

Want to find out more about this type of architecture, or need to implement these adaptations within your technical teams? Contact our team today!