Guide to Hexagonal Architecture

Get latest articles directly in your inbox
I was recently exploring one of old projects at work. Working on large codebases can soon get troublesome unless you follow a proper architecture. This is when I learned about hexagonal architecture. In this article i’ll share my learning around Hexagonal architecture and how to use it to design your projects.
Preparing for Interviews? I highly recommend Mastering System Design course on Educative.
Introduction
Hexagonal Architecture is a type of software architecture which was initally documented in 2005 by Alistair Cockburn. The architecture centers around the idea which to isolate the core business of an application and separate out input and outputs to a system. This helps in application being tested independently irrespective of external connections like database and code being reused when adding/removing data sources or end devices.
Problems
Dependency
Suppose the database server goes down or requires some rework or even replacement, now the developers are blocked because their work is tied to the presence of the database.
Code Reusability
Managing multiple data sources in same code base can result in repititive code and any changes in specific integration requires change in core system. Think about what changes will your code require to replace a postgres DB with mongo? Will your business logic be affected?
Vague Domain
You don’t want your business logic to be coupled with databases, external inputs, etc. This makes the application error prone and over time the code becomes unmanageable.
Main principles
- Separate business logic from input and data source (all external entities) .Remember dependencies always go inside business side i.e everything should depend on business logic not vice versa!
- Your code should not depend on any external components. It should not matter whether you serve API to android/ios/web or have Postgres/mongo or any other DB.
- To achieve this independence, we use an “Adapter” that let’s you maintain a single contract for your business logic component irrespective of I/O. What this means is that you have a single API and each external component can connect using specific adapters.
Components
Hexagonal Architecture involves breaking down your application in 3 components - User side, Core Business and Server side.
User side (Input)
This includes how user interacts with application. This can be done via external programs or directly by user.
Core Business
It contains all the code that concerns and implements business logic.
Server side
This includes all persistence, monitoring, logging and other components required for application. Eg. HTTP calls, Database interactions, etc.
Ports
Ports are endpoints provided by core business component via which external entities communicate. There will typically be multiple adapters for any one port, for various technologies that may plug into that port.
Adapters
The external entities say Postgres DB connect with core application using adapters which connect via port to the application. These adapters represent the external code make the glue between the port and the rest of the user-side code or server-side code.
Practical Example
Now that you understand basics around the architecture, let’s see a real world example of how this works.
In the diagram below, you can see a simple architecture for Payment Application which interacts with banks and users and process transactions. The data flow occurs from user and bank via interfaces into core payment application. Data is also fetched from DB to process transactions. Thus, data always flow inside core domain.
Input, Output and Core Domain
There can be multiple banks which connect via Bank Interface
(this would be a API). Similarly users can use the User Interface
and connect via mobile, web or other platforms. Now, the payment application processes transation. It fetches data payment data via Bank Repository
and user data via User Repository
. Once it has all relevant data it runs a set of validation checks and process transaction.
Ports and Adapters
This application has 4 ports and 4 interfaces with specific use cases. Each interface has ability to support multiple connections.
How it helps?
Now, we don’t have to worry about each bank, specific types of user. We can a clear way to connect to application and our business logic works independent of I/O entities.
Resources
- Hexagonal architecture principles by Octo
- Original article by Alistair Cockburn
- How Netflix uses Hexagonal Architecture
- Hexagonal Architecture — Principles & Practical Example in Java
I hope you learned something new. Feel free to suggest improvements ✔️
I share regular updates and resources on Twitter. Let’s connect!
Keep exploring 🔎 Keep learning 🚀
Liked the content? Do support :)