Hexagonal Architecture

May 10, 2026··
15 min read
Open full tree
Hexagonal ArchitectureFoundation of ArchitectureImplementation TechniquesDevelopment PracticesReal-World ApplicationsAdvanced Concepts

Hexagonal Architecture — A Deep Dive

Hexagonal Architecture (also known as the Ports and Adapters pattern) is a software architecture style intended to keep application core logic independent from external concerns (UI, databases, external services, messaging systems). It aims to make applications easier to test, evolve, and integrate by decoupling the business rules from their delivery mechanisms and infrastructure.

This article covers history, key concepts, theoretical foundations, practical implementations, comparisons with related architectures, code examples, testing strategies, migration guidance, common pitfalls, and future implications.

Table of contents

  • Introduction and motivations
  • History and origin
  • Core concepts
    • Ports and Adapters
    • Primary (driving) vs Secondary (driven) actors
    • Dependency rule and direction of flow
    • Hexagon metaphor
  • Theoretical foundations and principles
    • Single Responsibility Principle
    • Dependency Inversion Principle
    • Separation of concerns
    • Testability and inversion of control
  • Typical architecture and flows
  • Implementing Hexagonal Architecture
    • Design steps and boundaries
    • Folder/project structure examples
    • Example: Java + Spring (simple use case)
    • Example: Node/TypeScript (simple use case)
    • Example: C#/.NET (simple use case)
  • Complementary patterns and techniques
    • Domain-Driven Design (DDD)
    • CQRS and Event Sourcing
    • Messaging and event-driven systems
  • Testing strategies
    • Unit testing
    • Integration testing with adapters
    • Contract testing
    • End-to-end testing considerations
  • Deployment and operational considerations
    • Microservices and Hexagonal Architecture
    • Observability and monitoring
  • Comparisons with other architectures
    • Layered (n-tier)
    • Onion Architecture
    • Clean Architecture
  • Migration strategies and refactoring approaches
  • Common pitfalls and anti-patterns
  • Case studies and examples
  • Future trends and implications
  • Practical checklist and recommendations
  • Further reading

Introduction and motivations

When building software, you inevitably deal with two kinds of code:

  • Application (business) logic — the core domain rules and policies.
  • Infrastructure and delivery concerns — databases, web frameworks, messaging, UI, third-party APIs.

Hexagonal Architecture enforces a clear boundary between these concerns so the core domain remains independent from frameworks and external systems. This yields benefits:

  • Easier unit testing of domain logic without infrastructure dependencies.
  • Replaceable infrastructure (swap databases, UI, queue) with minimal impact.
  • Clear communication boundaries and better modularity.
  • Encourages explicit modeling of interaction points (ports) and their implementations (adapters).

History and origin

Hexagonal Architecture was proposed by Alistair Cockburn around 2005–2006. Cockburn's intent was to eliminate coupling between business logic and technology frameworks or delivery mechanisms and create a clear, testable architecture that supports different kinds of interactions with the application.

Cockburn used the hexagon as a metaphor: the application's core sits in the center, and each face of the hexagon is a port (an interface for communication). Adapters plug into ports to provide implementations for the outside world. Over time the pattern became widely known as "Ports and Adapters" and influenced other architectural styles: Onion Architecture (Jeffrey Palermo), Clean Architecture (Robert C. Martin), and more.

Core concepts

Ports and Adapters

  • Port: An abstract interface representing a required service or an offered capability. Ports are defined by the application core. They describe how the application expects to interact with external actors or services. Examples:
    • Repositories (persisting and retrieving domain entities)
    • Notification service (send emails)
    • Input interfaces (HTTP controllers, CLI commands)
  • Adapter: Concrete implementation that translates between the external world and the port. Adapters implement ports and live in the infrastructure layer. Examples:
    • SQL repository adapter using JDBC/ORM
    • REST controller adapter translating HTTP into application commands
    • Message queue adapter that routes messages to domain services

The key is that adapters depend on ports (interfaces), not the other way around.

Primary (driving) vs Secondary (driven) actors

  • Primary (driving) actors initiate interaction with the application: users, cron jobs, external systems calling the app. They are implemented by "driving adapters" that call the application through ports.
  • Secondary (driven) actors are services/devices the application calls: DB, external APIs, message brokers, email providers. They are implemented by "driven adapters" that implement ports the application expects.

This separation clarifies who initiates interactions and which parts are replaceable.

Dependency direction

The dependency rule: domain/core code should not depend on frameworks or infrastructure. Dependencies point inwards: adapters depend on the core interfaces. This aligns with the Dependency Inversion Principle (DIP).

Hexagon metaphor

Cockburn used a hexagon to show the app core surrounded by ports. The number of sides is arbitrary — the hexagon is a visual aid. The core defines the protocol, adapters plug into the ports, and the outside world interacts via adapters.

ASCII diagram:

Plain Text
1 +----------+ 2 / \ 3 UI <-| Application |-> DB 4 | Core | 5 CLI ->\ /-> Messaging 6 +----------+

Theoretical foundations and principles

Hexagonal Architecture embodies several software design principles:

  • Single Responsibility Principle: Keep domain logic focused on business rules; infrastructure concerns are separated into adapters.
  • Dependency Inversion Principle: High-level modules (domain) should not depend on low-level modules (DB). Both should depend on abstractions (ports).
  • Separation of Concerns: Each layer handles a distinct problem domain.
  • Interface Segregation: Ports should be focused interfaces tailored to use-cases.
  • Inversion of Control: The control flow is inverted — the application defines what it needs; adapters are injected.

These principles improve modularity, testability, and maintainability.

Typical architecture and flows

High-level components:

  • Domain model / business logic: Entities, value objects, domain services (pure, no I/O).
  • Application services / use cases: Orchestrate domain operations (still free of infrastructure).
  • Ports: Interfaces exposed by the application to be implemented by adapters.
  • Adapters:
    • Driving adapters (controllers, jobs, CLI) invoke application use cases.
    • Driven adapters (persistence, remote APIs, email clients) implement ports used by use cases.

Flow examples:

  1. User sends an HTTP request (driving adapter: Controller) → Controller calls application use case via port → Use case executes domain logic, uses repository port → Repository port implemented by DB adapter → DB adapter does I/O → Data returned to use case → Use case returns DTO to controller → Controller maps to HTTP response.

  2. Application needs to publish events → Application calls a MessagePort interface → Messaging adapter implements MessagePort sending messages to Kafka/RabbitMQ.

Implementing Hexagonal Architecture

Design steps and boundaries

  1. Identify core use cases: what the application must do.
  2. Define application services / use case classes that implement these use cases and express dependencies via interfaces (ports).
  3. Design domain model and domain services (pure behavior).
  4. Define ports for external interactions (persistence, external APIs, notifications).
  5. Implement adapters for each port (DB repositories, REST clients).
  6. Implement driving adapters: controllers, CLI, scheduled tasks.
  7. Wire dependencies via dependency injection at the composition root (application startup).

Key rule: Code inside the core (domain and use cases) must depend only on ports (interfaces) and domain objects.

Folder/project structure examples

Monolith single repo:

  • src/
    • domain/
      • model/
      • services/
    • application/
      • usecases/
      • ports/
    • adapters/
      • inbound/ (http, cli)
      • outbound/ (db, http clients, email)
    • config/ (composition root, DI)
    • tests/

Microservice with multiple projects (example in JVM):

  • service-core (domain + application ports + DTOs)
  • service-adapters (inbound + outbound adapters)
  • service-runner (composition root + deployment artifacts)

Example: Java + Spring Boot (simplified)

Domain and port:

Plain Text
1// domain/Order.java 2public class Order { 3 private UUID id; 4 private List<OrderItem> items; 5 // domain behavior... 6} 7 8// ports/OrderRepository.java 9public interface OrderRepository { 10 Optional<Order> findById(UUID id); 11 void save(Order order); 12}

Use case (application service):

Plain Text
1// application/PlaceOrderService.java 2@Component 3public class PlaceOrderService { 4 private final OrderRepository orderRepository; 5 private final PaymentGateway paymentGateway; // port for external payment service 6 7 public PlaceOrderService(OrderRepository orderRepository, 8 PaymentGateway paymentGateway) { 9 this.orderRepository = orderRepository; 10 this.paymentGateway = paymentGateway; 11 } 12 13 public OrderResult placeOrder(PlaceOrderCommand command) { 14 // business logic, validation, domain entity creation 15 // call paymentGateway.charge(...) 16 // save via orderRepository.save(order) 17 } 18}

Adapter (driven) — DB repository:

Plain Text
1// adapters/outbound/JpaOrderRepository.java 2@Repository 3public class JpaOrderRepository implements OrderRepository { 4 private final JpaOrderEntityRepository jpaRepo; // Spring Data JPA 5 6 public Optional<Order> findById(UUID id) { 7 return jpaRepo.findById(id).map(this::toDomain); 8 } 9 10 public void save(Order order) { 11 jpaRepo.save(toEntity(order)); 12 } 13}

Adapter (driving) — REST controller:

Plain Text
1// adapters/inbound/OrderController.java 2@RestController 3@RequestMapping("/orders") 4public class OrderController { 5 private final PlaceOrderService placeOrderService; 6 7 @PostMapping 8 public ResponseEntity<OrderResponse> placeOrder(@RequestBody PlaceOrderRequest req) { 9 var result = placeOrderService.placeOrder(req.toCommand()); 10 return ResponseEntity.ok(OrderResponse.from(result)); 11 } 12}

Composition root: Spring Boot config wires concrete adapters into constructors of the service (DI).

Example: Node / TypeScript

Interfaces (ports) and domain:

TypeScript
1// src/ports/orderRepository.ts 2import { Order } from "../domain/order"; 3 4export interface OrderRepository { 5 findById(id: string): Promise<Order | null>; 6 save(order: Order): Promise<void>; 7}

Use case:

TypeScript
1// src/usecases/placeOrder.ts 2import { OrderRepository } from "../ports/orderRepository"; 3import { PaymentGateway } from "../ports/paymentGateway"; 4 5export class PlaceOrder { 6 constructor(private repo: OrderRepository, private payment: PaymentGateway) {} 7 8 async execute(command: PlaceOrderCommand): Promise<OrderResult> { 9 // domain logic... 10 await this.payment.charge(...); 11 await this.repo.save(order); 12 return { orderId: order.id }; 13 } 14}

Adapter (inbound) using Express:

TypeScript
1// src/adapters/inbound/http/orderController.ts 2import express from "express"; 3import { PlaceOrder } from "../../../usecases/placeOrder"; 4 5export function orderRouter(placeOrder: PlaceOrder) { 6 const router = express.Router(); 7 router.post("/", async (req, res) => { 8 const result = await placeOrder.execute(req.body); 9 res.json(result); 10 }); 11 return router; 12}

Adapter (outbound) using a DB client:

TypeScript
1// src/adapters/outbound/postgresOrderRepo.ts 2import { OrderRepository } from "../../ports/orderRepository"; 3import { Pool } from "pg"; 4 5export class PostgresOrderRepo implements OrderRepository { 6 constructor(private pool: Pool) {} 7 async findById(id: string) { /* SQL mapping */ } 8 async save(order) { /* SQL upsert */ } 9}

Composition root:

TypeScript
1// src/app.ts 2import express from "express"; 3import { PlaceOrder } from "./usecases/placeOrder"; 4import { PostgresOrderRepo } from "./adapters/outbound/postgresOrderRepo"; 5import { StripePaymentGateway } from "./adapters/outbound/stripe"; 6 7const app = express(); 8const repo = new PostgresOrderRepo(/*...*/); 9const payment = new StripePaymentGateway(/*...*/); 10const placeOrder = new PlaceOrder(repo, payment); 11 12app.use("/orders", orderRouter(placeOrder));

Example: C# / .NET

Ports (interfaces) and use case:

Plain Text
1// Domain/Order.cs (entities) 2public class Order { /* ... */ } 3 4// Ports/IOrderRepository.cs 5public interface IOrderRepository { 6 Order Get(Guid id); 7 void Save(Order order); 8} 9 10// Application/PlaceOrder.cs 11public class PlaceOrder { 12 private readonly IOrderRepository _repo; 13 private readonly IPaymentGateway _payment; 14 public PlaceOrder(IOrderRepository repo, IPaymentGateway payment) { 15 _repo = repo; 16 _payment = payment; 17 } 18 19 public OrderResult Execute(PlaceOrderCommand cmd) { 20 // domain behavior 21 } 22}

Adapters are implemented in Infrastructure project and registered in Startup.cs/Program.cs.

Complementary patterns and techniques

  • Domain-Driven Design (DDD): Hexagonal Architecture works well with DDD. Domain model, aggregates, repositories (as ports) align naturally.
  • CQRS (Command Query Responsibility Segregation): Use commands for state changes (driving ports) and queries as separate use cases. Each can have its own ports/adapters.
  • Event Sourcing: Domain events can be produced by use cases and published via event ports; adapters write events to store or broker.
  • Functional Programming: Hexagonal architecture is compatible with FP approaches where pure functions represent domain logic and adapters are impure boundaries.

Testing strategies

Hexagonal Architecture makes testing predictable and layered:

  • Unit tests: Test domain entities and use cases in isolation by mocking ports (interfaces). No DB/HTTP required.
  • Adapter tests: Test adapter logic (mapping, translation) with integration tests that may use test containers or in-memory DB.
  • Integration tests: Start the system composing real adapters to verify end-to-end flows against test environments or lightweight doubles.
  • Contract tests: For services that expose APIs, use consumer-driven contract testing (e.g., Pact) to verify adapter behavior.
  • Acceptance/end-to-end tests: Validate whole system including UI and external integrations.

Benefits:

  • Fast and deterministic unit tests by exercising only core logic.
  • Clear separation reduces scope of integration tests.

Example: PlaceOrder use case unit test in Java with Mockito:

Plain Text
1@Test 2void placeOrder_success() { 3 var repo = mock(OrderRepository.class); 4 var payment = mock(PaymentGateway.class); 5 var service = new PlaceOrderService(repo, payment); 6 7 when(payment.charge(any())).thenReturn(PaymentResult.success()); 8 PlaceOrderCommand cmd = new PlaceOrderCommand(...); 9 10 var result = service.placeOrder(cmd); 11 12 verify(repo).save(any(Order.class)); 13 assertTrue(result.isSuccessful()); 14}

Deployment and operational considerations

Microservices and Hexagonal Architecture

  • Each microservice can adopt Hexagonal Architecture internally. The service core remains independent of how it's exposed (HTTP, gRPC, message).
  • Ports can represent service boundaries: e.g., event publishing port for communicating to other services or a REST adapter for syncing.
  • Compose hexagonal microservices with explicit contracts and adapters for service-to-service communication. Use contract testing to verify inter-service expectations.

Observability and monitoring

  • Because adapters are the integration points, incorporate logging, metrics, and tracing in adapters and the composition root. Keep domain code free of cross-cutting concerns except via explicit ports (e.g., MetricsPort).
  • Use middleware/adapters for instrumentation to avoid contaminating domain logic.

Comparisons with other architectures

  • Layered (n-tier): Typical layered architectures have tight coupling between layers and often the domain depends on infrastructure. Hexagonal isolates the domain from the infrastructure via interface-driven design.
  • Onion Architecture: Very similar; the onion places domain model at the center and layers outward. Ports conceptually live at the boundaries. Differences are mostly terminology and emphasis.
  • Clean Architecture (Uncle Bob): A superset/evolution emphasizing dependency rules and entities/use-cases/controllers. Very aligned with Hexagonal; Clean Architecture uses concentric circles instead of a hexagon.

In practice, these patterns share the same core principle: inward-facing dependencies and separation of domain logic.

Migration strategies and refactoring approaches

When migrating an existing codebase to Hexagonal Architecture:

  1. Identify a single use case or bounded context to refactor first.
  2. Extract domain logic into new domain/use-case classes that depend only on interfaces.
  3. Create ports (interfaces) representing external dependencies the extracted code requires.
  4. Implement adapters that wrap existing infrastructure and implement the interfaces.
  5. Replace calls to the old code with calls to the new use case; run tests.
  6. Iterate and migrate other modules.

Technique: The Strangler Fig pattern — gradually replace legacy components with hexagonal-designed modules until the legacy code is phased out.

Common pitfalls and anti-patterns

  • Defining ports that are too close to infrastructure concerns (e.g., SQL-specific methods) — ports should represent business intentions, not technical details.
  • Leaking frameworks into domain (e.g., domain classes depending on HTTP frameworks or ORM annotations).
  • Over-abstracting (creating unnecessary ports/adapters) leading to complexity and premature generalization.
  • Putting cross-cutting concerns directly into domain code: prefer dedicated ports (e.g., LoggerPort) or AOP/infrastructure.
  • Weak composition root: scattering wiring logic across the app erodes the benefits of inversion-of-control.

Case studies and examples

  1. E-commerce order processing:

    • Ports: OrderRepository, PaymentGateway, InventoryService, NotificationService.
    • Adapters: SQLRepository, StripeAdapter, InventoryHTTPAdapter, EmailAdapter.
    • Driving adapters: REST API for storefront, scheduled job for order cleanup.

  2. Event-sourced banking ledger:

    • Ports: EventStore, BalanceProjectionRepository, ExternalNotification.
    • Use cases: Deposit, Withdraw produce domain events written to EventStore adapter.

  3. IoT edge processing:

    • Ports: SensorReader, TelemetryPublisher.
    • Adapters: SerialPortAdapter, MQTTAdapter, WebSocketAdapter for UIs.

Future trends and implications

  • Cloud-native and serverless: Hexagonal architecture fits well because the core remains portable; serverless functions act as driving adapters.
  • Polyglot ecosystems and platform-as-a-service: Hexagonal modules can expose consistent ports for other teams to integrate.
  • Standardization of contract testing, API-first design and the rise of Interface-Driven Development complement ports-and-adapters ideas.
  • Increased adoption of asynchronous architectures (event-driven microservices) requires thoughtful port design for events, idempotence, and eventual consistency.
  • AI/ML integration: Treat model inference or feature stores as ports; adapters wrap the ML infra to keep domain logic insulated.

Practical checklist and recommendations

  • Start from use cases: model what the system should do before wiring frameworks.
  • Define ports as intent-driven interfaces — reflect business needs, not technical APIs.
  • Keep domain and use cases pure: no network, file, DB, or framework code.
  • Use dependency injection in a single composition root to wire adapters to ports.
  • Test domain logic with unit tests and mock ports; test adapters with integration tests.
  • Keep adapters thin: map to/from domain DTOs and handle technical details there.
  • Use contract tests for external collaborations (APIs, message formats).
  • Avoid over-abstraction — add ports when you need them or when abstraction buys testability or replaceability.

Further reading

  • Alistair Cockburn — "Hexagonal Architecture" (blog posts and essays)
  • Robert C. Martin — "Clean Architecture"
  • Eric Evans — "Domain-Driven Design" (DDD)
  • Vaughn Vernon — "Implementing Domain-Driven Design"
  • Articles and examples: Many project repos demonstrate Ports & Adapters in various languages (search for "ports and adapters example [language]").

Conclusion

Hexagonal Architecture is a pragmatic and powerful approach to designing maintainable, testable, and adaptable systems. By designing clear interfaces (ports) and isolating infrastructure concerns into adapters, teams can evolve technology choices, improve test coverage, and design robust systems resistant to framework or infrastructure churn. Whether used for monoliths, microservices, or serverless applications, the pattern helps keep business logic central and honest, which generally leads to better long-term outcomes.

If you'd like, I can:

  • Provide a concrete, full-featured sample project in Java/TypeScript/C# demonstrating hexagonal layering and tests.
  • Review an existing codebase and propose a migration plan to Hexagonal Architecture.
  • Generate detailed templates for ports, adapters, tests, and composition roots for a chosen language/framework.