Hexagonal Architecture

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

Core Concept

The application core (business logic) is surrounded by adapters that handle communication with external systems. The hexagon shape emphasizes that there’s no inherent “top” or “bottom” - all external systems are treated equally.

Components

Application Core (Inside the Hexagon)

• Contains business logic
• Defines ports (interfaces)
• Independent of external technologies

Ports

• Primary/Driving Ports: Interfaces for driving the application (e.g., use case interfaces)
• Secondary/Driven Ports: Interfaces for things the application needs (e.g., repository interfaces)

Adapters

• Primary/Driving Adapters: Trigger application (e.g., REST controllers, CLI, UI)
• Secondary/Driven Adapters: Implement infrastructure (e.g., database, message queue, external APIs)

Benefits

• Technology Independence: Swap databases, frameworks without changing core
• Testability: Test business logic with mock adapters
• Flexibility: Multiple adapters for same port (e.g., REST and GraphQL APIs)
• Clear Boundaries: Explicit separation of concerns

Example Structure

Application Core
├─ Domain Logic
├─ Ports (Interfaces)
   ├─ Driving: IOrderService
   └─ Driven: IOrderRepository

Adapters
├─ Driving
│  ├─ REST API Controller
│  └─ CLI
└─ Driven
   ├─ PostgreSQL Repository
   └─ Redis Cache

Visual Reference

From Architecture:

Resources

• Ports-And-Adapters
• BlueZone - Hexagonal Architecture in Java
• Hexagonal Architecture book

Related Concepts

• Clean Architecture
• Domain Driven Design
• Dependency Inversion Principle