Hexagonal Architecture (HA), also known as Ports and Adapters Architecture, is a foundational and influential software design pattern, first introduced by Alistair Cockburn in 2005.
The term “Hexagonal Architecture” comes from a visual convention: the application component is drawn as a hexagon, not to imply it must have six boundaries or ports, but to leave enough space to represent the different interfaces connecting the component to the outside world. As Cockburn stated in his 2005 article:
The hexagon is not a hexagon because the number six is important, but rather to allow the people doing the drawing to have room to insert ports and adapters as they need, not being constrained by a one-dimensional layered drawing.
This insight is crucial—it reminds us to stop focusing on the shape and instead focus on the core concept: defining the application’s API via ports and connecting it to the outside world with interchangeable adapters. This shift from diagram to intent is the first step toward architectural maturity.
Ports & Adapters (Hexagonal Architecture) explicitly defines two layers: the inside (application core) and the outside (everything else), and requires clear definition of ports for interaction.
(Clean Architecture builds on this by further splitting the application core into more granular layers such as Use Cases, Entities, and Domain Services, but is less prescriptive about the “port” metaphor for the outer boundary.)
Core Principles
Application Core: The fundamental goal of HA is isolation and decoupling. It contains only business logic and is completely independent of the outside world.
Ports: Abstract contracts (interfaces) defining how to communicate with the outside, e.g., reading/writing data or sending notifications.
Adapters: Concrete implementations that transform external requests or resources into a format understood by the core.
- Protect Core Business Logic: Avoid structural flaws known in object-oriented design, such as unnecessary dependencies between layers or contamination of business logic by UI code. The pattern isolates the core logic from changes in external dependencies like databases, UI, or frameworks.
- Independence and Testability: Allows the application to be driven by users, programs, automated tests, or batch scripts while keeping development and testing isolated from the runtime database or UI.
- Architectural Symmetry: HA solves the entanglement of application logic and external entities (e.g., client and server) seen in traditional layered architectures. It emphasizes asymmetry between the core and external entities while treating all external components symmetrically.
Adapter Practical Examples
| Adapter Type | Spring Boot Implementation | Description |
|---|---|---|
| Database Access | Repository using JPA / Hibernate or JDBC Template | Implements the RepositoryPort interface, mapping database CRUD operations into a format the core can understand. The core does not directly depend on ORM. |
| External APIs | RestTemplate / WebClient / gRPC Stub / Socket client |
Adapters call external systems; the core only depends on the interface (Port), unaware of HTTP, gRPC, or Socket details. |
| User Interface | Spring MVC Controller / WebFlux Handler | Controller receives requests → maps to DTO → calls Use Case → returns response. Core logic does not depend on the web framework. |
| Event / Messaging | Kafka / RabbitMQ Adapter | External events are converted by Adapter into core events or Use Case calls; the core is unaware of the messaging system. |
| Testing | Test-specific Fake Adapter | Core logic can be tested with fake adapters, without requiring a database or UI. |
Key Observations
DB Adapter: Using an ORM is just a means. The core logic does not depend on JPA/Hibernate and could easily be replaced with MyBatis or JDBC.
External APIs: HTTP, gRPC, or Socket are just adapter implementations; the core logic does not care about the actual protocol.
Flexible Composition: Controller, Kafka, Scheduler, CLI, etc., can all be adapters while the core logic remains unchanged.
Testability: Core logic can be unit-tested with fake or mock adapters without starting a DB or Web Server.
In short: Hexagonal Architecture does not dictate ORM or HTTP implementation details. It only requires that the core logic is decoupled from the outside world. Any technology can act as an adapter.
Ultimately, Hexagonal, Clean, Onion, or other architectural labels are less important than the discipline they enforce. They are all tools for building systems that respect the most critical architectural boundary: the one between your core business logic and the ever-changing details of technology.
Understanding these principles allows you to make pragmatic decisions that fit the context of your project, team, and business. The next time you start a project, don’t ask, “Should I use Hexagonal or Clean Architecture?” A better question is:
“How can I protect my core business logic in the simplest and most testable way from the details that are bound to change?”
References
Hexagonal architecture the original 2005 article https://alistair.cockburn.us/hexagonal-architecture
Hexagonal architecture (software) https://en.wikipedia.org/wiki/Hexagonal_architecture_(software)