Hexagonal Architecture Explained

What is Hexagonal Architecture?

Hexagonal Architecture, also known as Ports & Adapters, is a way of organizing your code so that the Domain (business logic) does not depend on frameworks, databases, or external APIs. By isolating business logic from external technical concerns, it becomes significantly easier to test and maintain your code.

Your business is what matters; technology simply adapts to it.

The Problem It Solves

Before Hexagonal Architecture, many projects followed a traditional layered structure where business logic was tightly coupled with data access:

If you ever need to migrate from PostgreSQL to MongoDB, you face a massive problem. Why? Because the code is coupled to specific technologies.

The Importance of the Domain

In this model, the domain is technology-agnostic. It doesn't know the outside world exists, the domain doesn't know what a JSON is, let alone what a database is. It is the outside world that must adapt to the domain.

The domain contains the following elements:

• Entities
• Business Rules
• Use cases
• Ports (Interfaces)

This Core knows nothing about specific technologies like Spring, JPA, JSON, etc.

🚪 Ports

Ports are interfaces defined by the domain. The domain says: "I need to save users, I don't care how." For example: "I need a method to persist a user, and I don't care where or through what process it happens."

🔌 Adapters

Adapters are the actual implementations using specific technologies.

• Primary Adapters (Driving): These initiate the action. They are the entry point (e.g., REST Controllers, CLI).
• Secondary Adapters (Driven): These are tools the Domain uses. They are the exit point (e.g., SQL Repository implementations, Email clients, third-party APIs).

The Hexagonal Architecture Flow

• Domain & Application: The center of the hexagon. This is where the logic resides, logic that doesn't change if you switch your database or web framework.
• Ports: The "windows" of the hexagon. They define how to interact with the Core without the Core needing to know who is calling it.
• Adapters: The bridge between the outside world and the ports.
  • Primary (Driving): Trigger actions (e.g., a controller receiving an HTTP request).
  • Secondary (Driven): Called by the application (e.g., a SQL adapter implementing a repository interface).

Benefits

• Low Coupling: You can swap your database or email provider in much less time.
• Easier Testing: You can test business logic without spinning up a database or a server.
• High Maintainability: Cleaner, more readable code.
• Framework Independence: You aren't "married" to external tools or frameworks.

Hexagonal Architecture is not just a trend or unnecessary over-engineering, it's a way of stating that the business is the most important part, everything else is replaceable.

If you want to learn more, you can see how the hexagonal architecture is implemented in a project.

Comments