Hexagonal Architecture Explained

Ports and Adapters — the pattern that makes business logic technology-agnostic by defining clear interfaces between the core and the outside world.

Hexagonal Architecture

Hexagonal Architecture (Ports and Adapters) is a software design pattern by Alistair Cockburn that structures applications around the core business logic, using ports (interfaces) for input/output and adapters to connect to external systems.

Explanation

Traditional layered architectures create a dependency chain: UI depends on business logic, which depends on the database. Hexagonal Architecture breaks these chains by placing the application core at the center, surrounded by ports (interfaces that the core defines) and adapters (implementations that connect ports to external systems). Ports are contracts defined by the application core. A "driving port" (primary) defines how the outside world interacts with the application (e.g., an HTTP API, a CLI command). A "driven port" (secondary) defines what the application needs from the outside world (e.g., a database, an email service). Adapters implement these ports for specific technologies. The hexagonal shape (though the number of sides is irrelevant) emphasizes that there are many ways to interact with the application, and all are equivalent. A REST adapter and a GraphQL adapter both drive the same use cases through the same ports. A PostgreSQL adapter and a MongoDB adapter both satisfy the same repository port. This makes the application core technology-agnostic and highly testable.

Bookuvai Implementation

Bookuvai uses Hexagonal Architecture for service boundaries in microservices projects. Each service defines clear port interfaces for its inputs (API endpoints, event handlers) and outputs (database repositories, external service clients). Adapters are swappable — enabling mock adapters for testing and real adapters for production without changing business logic.

Key Facts

  • Also known as Ports and Adapters pattern
  • Coined by Alistair Cockburn in 2005
  • Ports are interfaces defined by the application core
  • Adapters implement ports for specific technologies (HTTP, SQL, etc.)
  • Enables technology-agnostic business logic and easy adapter swapping

Related Terms

Frequently Asked Questions

Why is it called "hexagonal"?
The hexagonal shape is arbitrary — Cockburn chose it to emphasize that there are multiple ports (sides) of equal importance, unlike a layered architecture where the database is at the bottom. The number six has no special significance.
What is the difference between a port and an adapter?
A port is an interface defined by the application core (e.g., UserRepository with save/find methods). An adapter implements that interface for a specific technology (e.g., PostgresUserRepository). The core depends on the port, not the adapter.
How does Hexagonal Architecture help testing?
Business logic depends only on port interfaces, not concrete implementations. In tests, swap real adapters with in-memory or mock adapters. No database, no HTTP server, no external services — just fast, isolated unit tests.