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

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

2. 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?

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

1. User side (Input)

   This includes how user interacts with application. This can be done via external programs or directly by user.

2. Core Business

   It contains all the code that concerns and implements business logic.

3. Server side

   This includes all persistence, monitoring, logging and other components required for application. Eg. HTTP calls, Database interactions, etc.

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

5. 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 🚀