Concepts

Hexagonal Architecture

Architectural pattern isolating business logic from the outside world through ports and adapters, facilitating testing and technology changes.

seed#hexagonal#ports-adapters#clean-architecture#architecture#patterns#testing

What it is

Hexagonal architecture (also called Ports & Adapters) organizes code in layers where business logic is at the center, completely isolated from technical details like databases, APIs, or frameworks.

Structure

[HTTP Adapter] → [Input Port] → [Domain] → [Output Port] → [DB Adapter]
  • Domain: pure business logic, no external dependencies
  • Ports: interfaces defining how the domain interacts with the outside
  • Adapters: concrete implementations of ports

Benefits

  • Domain testing without infrastructure
  • Change database without touching business logic
  • Multiple interfaces (HTTP, CLI, events) for the same logic
  • Clear separation of responsibilities

Relationship with other architectures

ArchitectureAuthorLayersKey difference
Hexagonal (Ports & Adapters)Alistair Cockburn, 2005Domain → Ports → AdaptersFocus on ports as contracts
Clean ArchitectureRobert Martin, 2012Entities → Use Cases → Adapters → FrameworksConcentric layers, dependencies point inward
Onion ArchitectureJeffrey Palermo, 2008Domain Model → Domain Services → Application → InfrastructureSimilar to Clean, emphasis on domain model

All three share the fundamental principle: dependencies point inward, protecting business logic from infrastructure details.

Why it matters

Hexagonal architecture protects business logic from infrastructure details. When the database, web framework, or cloud provider changes, only the adapters are modified — the domain remains intact. It is the investment in long-term maintainability.

References

Concepts