Hexagonal Architecture (Ports and Adapters)

Reference: Hexagonal Architecture Explained (Cockburn & Garrido de Paz), Get Your Hands Dirty on Clean Architecture (Hombergs)

When to Apply

• Structuring an application so business logic is independent of delivery mechanism and infrastructure
• Defining port interfaces for external system interactions
• Implementing adapters for databases, message queues, REST APIs, or CLI
• Testing business logic in isolation from infrastructure
• Deferring technology decisions (database, framework, messaging) to the last reasonable moment
• Migrating a tightly coupled application toward decoupled architecture

Core Concept

Alistair Cockburn published the pattern in 2005 (roots back to 1994). The hexagon shape was chosen to break away from layered stack diagrams — it is not about the number six.

Core intent: "Allow an application to equally be driven by users, programs, automated tests, or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases."

Fundamental rule: The application core defines ALL port interfaces. Adapters depend on ports. The core MUST NOT depend on adapters.

Ports

Ports are interfaces belonging to the application core — they are NOT a separate layer.

Driving (Primary) Ports

Interfaces the application exposes for external actors to call INTO the application.

• Define the application's capabilities from the outside world's perspective
• Connected to primary actors: users, other systems, tests, batch jobs
• SHOULD be named by capability: ForPlacingOrders, ForManagingInventory, ForQueryingReports

Driven (Secondary) Ports

Interfaces the application requires from external systems — what the application needs but does not implement.

• Define what services the application expects the outside world to provide
• Connected to secondary actors: databases, message queues, external APIs, file systems
• SHOULD be named by need: ForStoringOrders, ForSendingNotifications, ForFetchingExchangeRates

Port Design Rules

• MUST define port interfaces in the application core, not in the adapter layer
• MUST express ports in domain language, not technology language (ForStoringOrders not DatabasePort)
• MUST NOT include technology-specific types in port signatures (no SQL types, HTTP objects, or ORM entities)
• SHOULD keep ports focused — one port per actor interaction concern

Adapters

Adapters are concrete implementations that connect ports to the outside world.

Primary (Driving) Adapters

Translate external input into calls on driving ports. They call INTO the application.

Secondary (Driven) Adapters

Implement driven port interfaces. The application calls THROUGH them.

Adapter Rules

• MUST implement exactly one port interface per adapter (adapters are single-purpose)
• MUST NOT contain business logic — only translation and delegation
• MUST NOT be referenced by the application core — the core knows only the port interface
• SHOULD be swappable: replacing PostgresOrderRepository with MongoOrderRepository requires no core changes

Application Core Structure

The hexagon's interior contains all business logic, free from infrastructure concerns:

core/
  domain/
    model/          # Entities, Value Objects, Aggregates
    service/        # Domain services (stateless business rules)
  application/
    port/
      driving/      # Driving port interfaces (ForPlacingOrders)
      driven/       # Driven port interfaces (ForStoringOrders)
    service/        # Application services (use case orchestration)

• MUST NOT import any framework, database, or HTTP library in the core
• MUST NOT reference any adapter class from within the core
• SHOULD separate domain model from application services (domain contains pure business rules; application coordinates use cases)

Testing Strategy

The hexagonal architecture's primary advantage is testability through adapter substitution.

Test Progression

• MUST write tests against port interfaces, not adapter implementations
• SHOULD start with in-memory adapters during development; add real adapters incrementally
• SHOULD use the test harness as a first-class driving adapter — it validates the entire core without infrastructure

Relationship to Other Architectures

All three share the same DNA: business logic at center, dependencies point inward, DIP at architectural level.

• SHOULD choose hexagonal when the team values simplicity and flexibility in internal core organization
• SHOULD choose clean architecture when the team benefits from prescriptive layer naming and component principles
• All three are valid; the important invariant is dependencies point inward

Common Pitfalls

Checklist

When designing or reviewing a hexagonal architecture, verify:

• The application core defines all port interfaces — no port is defined in an adapter
• Driving ports express application capabilities in domain language
• Driven ports express application needs in domain language — no technology types
• Primary adapters translate external input and call driving ports
• Secondary adapters implement driven ports and connect to external systems
• The core has zero imports from frameworks, databases, or HTTP libraries
• No adapter is referenced from within the core
• Business logic lives in the core, not in adapters
• Tests run against ports using in-memory adapters for fast feedback
• Adapters are swappable without modifying core code

Key References

Online References

• Alistair Cockburn's original article: alistair.cockburn.us/hexagonal-architecture
• Netflix Tech Blog: "Ready for Changes with Hexagonal Architecture" (2020)
• AWS Prescriptive Guidance: "Building Hexagonal Architectures on AWS" (2023)