Hexagonal Architecture

Core Idea

Hexagonal Architecture (also known as Ports and Adapters) isolates core business logic from external concerns through well-defined interfaces.

Definition

Hexagonal Architecture (also known as Ports and Adapters) isolates core business logic from external concerns through well-defined interfaces. Invented by Alistair Cockburn in the early 2000s, it prevents undesired dependencies between layers and contamination of business logic with infrastructure code. The hexagonal shape provides visual space for multiple ports and adapters, unconstrained by traditional layered drawings.

Key Characteristics

• Dependency inversion: External concerns depend on core through ports—business logic remains technology-agnostic
• Ports as contracts: Technology-agnostic interfaces representing use cases
• Adapters as implementations: Technology-specific code transforming data between external formats and domain models
• Business logic isolation: Core protected from infrastructure changes—swap technologies via new adapters only
• Testability by design: Test logic without infrastructure using test adapters
• Symmetry: Input and output sides treated equally
• Multiple adapters per port: Single port supports multiple implementations
• Primary ports: Expose capabilities to initiators (REST, CLI)
• Secondary ports: Define dependencies on resources (repositories, publishers)

Examples

• Payment processing: Core defines PaymentPort; Stripe, PayPal, test adapters implement it—swap processors by changing adapters only
• Multi-channel service: CreateTicketPort has web, mobile, email adapters—tickets from any channel without logic duplication
• Cloud-agnostic storage: FileStoragePort with S3, Azure, local adapters—deploy anywhere

Why It Matters

Protection against logic leakage: Explicit boundaries prevent business rules migrating into controllers, triggers, or UI. Long-running systems swap entire technology stacks while keeping core pure.

DDD foundation: Structural home for aggregates, entities, value objects, and domain services free from infrastructure concerns.

Testing simplification: Validates workflows using in-memory adapters—no infrastructure setup, faster tests, higher reliability.

Technology evolution: Replace frameworks, databases, or protocols via adapter changes rather than rewrites—lower risk and cost.

Related Concepts

• Coupling (hexagonal architecture minimizes coupling between domain and infrastructure)
• Bounded-Context (hexagon boundaries often align with DDD bounded contexts)
• Modularity (ports and adapters promote modular design)
• Testability (architecture enables comprehensive testing without infrastructure)
• Contract (ports are contracts between core and periphery)
• Implementation-Coupling (pattern eliminates implementation coupling)
• Component (hexagon represents a cohesive component)

Sources

• Cockburn, Alistair (2005). “Hexagonal Architecture.”

  • Available: https://alistair.cockburn.us/hexagonal-architecture
  • Original article from pattern’s inventor

• Cockburn, Alistair and Garrido de Paz, Juan Manuel (2024). Hexagonal Architecture Explained. ISBN: 978-1737519782.

  • Available: https://www.hexagonalarchitecture.org/

• Ford, Neal; Richards, Mark; Sadalage, Pramod; Dehghani, Zhamak (2022). Software Architecture: The Hard Parts. O’Reilly. ISBN: 978-1-492-08689-5.

  • Chapter 8: Reuse Patterns

• AWS Prescriptive Guidance (2023). “Hexagonal architecture pattern.”

  • Available: https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/hexagonal-architecture.html

• Graça, Herberto (2017). “Ports & Adapters Architecture.” Software Architecture Chronicles.

  • Available: https://medium.com/the-software-architecture-chronicles/ports-adapters-architecture-d19f2d476eca

• Code Soapbox (2023). “Ports & Adapters explained.”

  • Available: https://codesoapbox.dev/ports-adapters-aka-hexagonal-architecture-explained/

AI Assistance

This content was drafted with assistance from AI tools for research, organization, and initial content generation. All final content has been reviewed, fact-checked, and edited by the author to ensure accuracy and alignment with the author’s intentions and perspective.