{"title":"Hexagonal Architecture","description":"","content":"Throughout this section, we have explored architectures at the system level: how services are organized, how they communicate, how they scale. But there is another dimension of architecture that is equally important: how we organize code within a single application.\n\n**Hexagonal architecture**, also known as Ports and Adapters, addresses this internal structure. It proposes a way to organize code that keeps business logic independent from technical details like databases, web frameworks, and external services. The core application knows nothing about how it is accessed or where data is stored.\n\nThis independence brings powerful benefits. You can test business logic without databases or HTTP servers. You can swap databases without changing business rules. You can add new interfaces without touching the core. The application becomes more maintainable, more testable, and more adaptable to change.\n\nIn this chapter, you will learn:\n\n- The core principles of hexagonal architecture\n- How ports and adapters work\n- Organizing code into layers with clear dependencies\n- The relationship between hexagonal and other architectural patterns\n- Practical implementation guidelines\n- When this approach is worth the investment\n\n---\n\n# The Problem: Entangled Code\n\nTraditional layered applications often develop problematic dependencies:\n\n\n```mermaid\nflowchart TB\n subgraph Traditional[\"Traditional Layered Architecture\"]\n UI[UI Layer]:::primary\n BL[Business Logic]:::orange\n DAL[Data Access Layer]:::teal\n DB[(Database)]:::purple\n EXT[External APIs]:::rose\n end\n\n UI --> BL\n BL --> DAL\n DAL --> DB\n BL --> EXT\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef purple fill:#9775fa,stroke:#000,color:#000\n classDef rose fill:#f783ac,stroke:#000,color:#000\n```\n\n\nThis looks clean, but problems emerge:\n\n\n```shell\nProblem 1: Business logic depends on database\n─────────────────────────────────────────────────────\nclass OrderService {\n private OrderRepository repo; // Concrete implementation\n\n public Order createOrder(OrderRequest req) {\n // Business logic intertwined with data access\n Order order = new Order(req);\n repo.save(order); // What if we want to test without DB?\n return order;\n }\n}\n\nProblem 2: Can't test without infrastructure\n─────────────────────────────────────────────────────\nTo test OrderService, you need:\n- Running database\n- Test data setup\n- Connection configuration\nTests are slow and fragile.\n\nProblem 3: Framework lock-in\n─────────────────────────────────────────────────────\nSpring annotations throughout business logic\nJPA entities in domain model\nHTTP concerns leaking into services\n```\n\n\nThe business logic, the most valuable part of your application, becomes hostage to infrastructure decisions.\n\n---\n\n# The Hexagonal Solution\n\nHexagonal architecture inverts these dependencies. The business logic is at the center, knowing nothing about the outside world. External concerns connect through abstractions called ports.\n\n\n```mermaid\nflowchart TB\n subgraph Hexagon[\"Application Core\"]\n Domain[Domain Model]:::orange\n Services[Application Services]:::orange\n end\n\n subgraph Primary[\"Primary/Driving Adapters\"]\n REST[REST API]:::primary\n CLI[CLI]:::primary\n Events[Event Consumer]:::primary\n end\n\n subgraph Secondary[\"Secondary/Driven Adapters\"]\n Postgres[PostgreSQL Adapter]:::teal\n S3[S3 Adapter]:::teal\n Email[Email Adapter]:::teal\n end\n\n REST --> |Port| Hexagon\n CLI --> |Port| Hexagon\n Events --> |Port| Hexagon\n\n Hexagon --> |Port| Postgres\n Hexagon --> |Port| S3\n Hexagon --> |Port| Email\n\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\n### The Core Principle\n\n**The application core has no dependencies on external systems.**\n\n- Business logic does not know about HTTP, databases, or message queues\n- All external access goes through abstract ports\n- Adapters implement ports to connect to specific technologies\n- Dependencies point inward, never outward\n\n---\n\n# Ports and Adapters\n\n### Ports\n\nPorts are interfaces that define how the outside world can interact with the application:\n\n\n```shell\nPrimary Ports (Inbound):\n─────────────────────────────────────────────────────\nDefine what the application CAN DO\nCalled by external actors (users, other systems)\nExamples:\n- CreateOrderUseCase\n- GetProductCatalog\n- ProcessPayment\n\nSecondary Ports (Outbound):\n─────────────────────────────────────────────────────\nDefine what the application NEEDS\nCalled by the application to access external resources\nExamples:\n- OrderRepository\n- PaymentGateway\n- EmailSender\n```\n\n\n### Adapters\n\nAdapters are implementations that connect ports to specific technologies:\n\n\n```shell\nPrimary Adapters (Driving):\n─────────────────────────────────────────────────────\nConvert external requests to calls on primary ports\nExamples:\n- REST Controller → calls CreateOrderUseCase\n- CLI Command → calls GetProductCatalog\n- Kafka Consumer → calls ProcessPayment\n\nSecondary Adapters (Driven):\n─────────────────────────────────────────────────────\nImplement secondary ports with specific technology\nExamples:\n- PostgresOrderRepository implements OrderRepository\n- StripePaymentGateway implements PaymentGateway\n- SendGridEmailSender implements EmailSender\n```\n\n\n### Visual Representation\n\n\n```mermaid\nflowchart LR\n subgraph Primary[\"Primary Adapters\"]\n REST[REST Controller]:::primary\n end\n\n subgraph Core[\"Application Core\"]\n PP[Primary Port
CreateOrderUseCase]:::orange\n APP[Application Logic]:::orange\n SP[Secondary Port
OrderRepository]:::orange\n end\n\n subgraph Secondary[\"Secondary Adapters\"]\n PG[PostgresOrderRepository]:::teal\n end\n\n REST -->|Calls| PP\n PP --> APP\n APP --> SP\n SP -.->|Interface| PG\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\n---\n\n# Dependency Rule\n\nThe fundamental rule of hexagonal architecture:\n\n**Dependencies point inward. The core knows nothing about the outside.**\n\n\n```mermaid\nflowchart TB\n subgraph Outer[\"Infrastructure Layer\"]\n DB[(Database)]:::purple\n HTTP[HTTP]:::purple\n Queue[Message Queue]:::purple\n end\n\n subgraph Middle[\"Adapter Layer\"]\n REST[REST Adapter]:::teal\n Repo[Repository Adapter]:::teal\n Msg[Message Adapter]:::teal\n end\n\n subgraph Inner[\"Application Core\"]\n Domain[Domain]:::orange\n end\n\n DB --> Repo\n HTTP --> REST\n Queue --> Msg\n\n REST --> Domain\n Repo --> Domain\n Msg --> Domain\n\n classDef purple fill:#9775fa,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n```\n\n\n### What This Means in Code\n\n\n```shell\nWRONG: Core depends on infrastructure\n─────────────────────────────────────────────────────\n// In domain layer\nimport org.springframework.data.jpa.repository.JpaRepository;\nimport com.amazonaws.services.s3.AmazonS3;\n\nclass OrderService {\n private JpaRepository repo; // Framework dependency\n private AmazonS3 s3; // AWS dependency\n}\n\nRIGHT: Core depends only on abstractions it defines\n─────────────────────────────────────────────────────\n// In domain layer - defines its own interface\ninterface OrderRepository {\n Order save(Order order);\n Optional findById(OrderId id);\n}\n\nclass OrderService {\n private OrderRepository repo; // Interface defined in domain\n}\n\n// In adapter layer - implements interface\nclass PostgresOrderRepository implements OrderRepository {\n private JpaRepository jpa; // Framework here, not in core\n\n public Order save(Order order) {\n OrderEntity entity = toEntity(order);\n jpa.save(entity);\n return order;\n }\n}\n```\n\n\n---\n\n# Project Structure\n\nA typical hexagonal project organizes code into three main areas:\n\n\n```shell\nsrc/\n├── domain/ # The Application Core\n│ ├── model/ # Domain entities and value objects\n│ │ ├── Order.java\n│ │ ├── OrderId.java\n│ │ └── OrderStatus.java\n│ ├── port/\n│ │ ├── in/ # Primary ports (use cases)\n│ │ │ ├── CreateOrderUseCase.java\n│ │ │ └── GetOrderUseCase.java\n│ │ └── out/ # Secondary ports (repositories, gateways)\n│ │ ├── OrderRepository.java\n│ │ └── PaymentGateway.java\n│ └── service/ # Application services implementing use cases\n│ └── OrderApplicationService.java\n│\n├── adapter/ # Adapters (Infrastructure)\n│ ├── in/ # Primary adapters\n│ │ ├── web/\n│ │ │ └── OrderController.java\n│ │ └── cli/\n│ │ └── OrderCommand.java\n│ └── out/ # Secondary adapters\n│ ├── persistence/\n│ │ └── PostgresOrderRepository.java\n│ └── payment/\n│ └── StripePaymentGateway.java\n│\n└── config/ # Dependency injection configuration\n └── ApplicationConfig.java\n```\n\n\n### Module Dependencies\n\n\n```mermaid\nflowchart TB\n subgraph Modules\n A[adapter module]:::teal\n D[domain module]:::orange\n C[config module]:::primary\n end\n\n A -->|depends on| D\n C -->|depends on| A\n C -->|depends on| D\n\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef primary fill:#00ceff,stroke:#000,color:#000\n```\n\n\n- **domain** has no external dependencies\n- **adapter** depends on domain (and external libraries)\n- **config** wires everything together\n\n---\n\n# Implementing Ports\n\n### Primary Port (Use Case)\n\nDefines what the application can do:\n\n\n```shell\n// Primary port: What the application offers\ninterface CreateOrderUseCase {\n OrderId execute(CreateOrderCommand command);\n}\n\n// Command object: Input data\nclass CreateOrderCommand {\n private CustomerId customerId;\n private List items;\n private ShippingAddress address;\n // No HTTP-specific details (headers, response codes)\n // Pure business data\n}\n```\n\n\n### Secondary Port (Repository)\n\nDefines what the application needs:\n\n\n```shell\n// Secondary port: What the application requires\ninterface OrderRepository {\n Order save(Order order);\n Optional findById(OrderId id);\n List findByCustomer(CustomerId customerId);\n}\n\n// Note: Interface defined by the domain\n// Implementation chosen by adapter\n// Domain doesn't know if it's SQL, MongoDB, or in-memory\n```\n\n\n### Application Service\n\nImplements use cases by orchestrating domain logic:\n\n\n```shell\nclass OrderApplicationService implements CreateOrderUseCase {\n private final OrderRepository orderRepository;\n private final PaymentGateway paymentGateway;\n private final InventoryService inventoryService;\n\n @Override\n public OrderId execute(CreateOrderCommand command) {\n // Pure business logic\n Order order = Order.create(\n command.getCustomerId(),\n command.getItems()\n );\n\n inventoryService.reserve(order.getItems());\n\n PaymentResult payment = paymentGateway.charge(\n order.getTotal(),\n command.getPaymentDetails()\n );\n\n if (payment.isSuccessful()) {\n order.markAsPaid(payment.getTransactionId());\n orderRepository.save(order);\n return order.getId();\n } else {\n throw new PaymentFailedException(payment.getError());\n }\n }\n}\n```\n\n\n---\n\n# Implementing Adapters\n\n### Primary Adapter (REST Controller)\n\nConverts HTTP to use case calls:\n\n\n```shell\nclass OrderController {\n private final CreateOrderUseCase createOrderUseCase;\n\n @PostMapping(\"/orders\")\n ResponseEntity createOrder(@RequestBody OrderRequest request) {\n // Convert HTTP request to domain command\n CreateOrderCommand command = new CreateOrderCommand(\n CustomerId.of(request.getCustomerId()),\n mapItems(request.getItems()),\n mapAddress(request.getShippingAddress())\n );\n\n // Call use case\n OrderId orderId = createOrderUseCase.execute(command);\n\n // Convert domain result to HTTP response\n return ResponseEntity\n .created(URI.create(\"/orders/\" + orderId))\n .body(new OrderResponse(orderId.getValue()));\n }\n}\n```\n\n\nThe controller's job:\n\n1. Parse HTTP request\n2. Create domain command\n3. Call use case\n4. Format HTTP response\n\nNo business logic in the controller.\n\n### Secondary Adapter (Repository)\n\nImplements repository port with specific technology:\n\n\n```shell\nclass PostgresOrderRepository implements OrderRepository {\n private final JdbcTemplate jdbc;\n\n @Override\n public Order save(Order order) {\n jdbc.update(\n \"INSERT INTO orders (id, customer_id, status, total) VALUES (?, ?, ?, ?)\",\n order.getId().getValue(),\n order.getCustomerId().getValue(),\n order.getStatus().name(),\n order.getTotal()\n );\n\n // Save order items\n for (OrderItem item : order.getItems()) {\n jdbc.update(\n \"INSERT INTO order_items (...) VALUES (...)\",\n ...\n );\n }\n\n return order;\n }\n\n @Override\n public Optional findById(OrderId id) {\n // Query and map back to domain object\n // Domain doesn't know about JdbcTemplate, SQL, or table structure\n }\n}\n```\n\n\n---\n\n# Testing Benefits\n\nHexagonal architecture makes testing significantly easier:\n\n### Unit Testing Domain Logic\n\n\n```shell\nclass OrderApplicationServiceTest {\n private CreateOrderUseCase useCase;\n private InMemoryOrderRepository orderRepo;\n private MockPaymentGateway paymentGateway;\n\n @BeforeEach\n void setup() {\n orderRepo = new InMemoryOrderRepository(); // In-memory fake\n paymentGateway = new MockPaymentGateway(); // Mock\n useCase = new OrderApplicationService(orderRepo, paymentGateway, ...);\n }\n\n @Test\n void shouldCreateOrderWhenPaymentSucceeds() {\n paymentGateway.willSucceed();\n\n OrderId orderId = useCase.execute(validCommand());\n\n assertThat(orderRepo.findById(orderId)).isPresent();\n }\n\n @Test\n void shouldNotSaveOrderWhenPaymentFails() {\n paymentGateway.willFail(\"Insufficient funds\");\n\n assertThrows(PaymentFailedException.class,\n () -> useCase.execute(validCommand()));\n\n assertThat(orderRepo.findAll()).isEmpty();\n }\n}\n```\n\n\n**No database. No HTTP server. No external services. Fast, reliable tests.**\n\n### Testing Adapters\n\nTest adapters against real infrastructure:\n\n\n```shell\n@SpringBootTest\nclass PostgresOrderRepositoryTest {\n @Autowired\n private OrderRepository repository; // Real PostgreSQL\n\n @Test\n void shouldPersistAndRetrieveOrder() {\n Order order = createTestOrder();\n\n repository.save(order);\n Optional found = repository.findById(order.getId());\n\n assertThat(found).contains(order);\n }\n}\n```\n\n\n### The Testing Pyramid\n\n\n```mermaid\nflowchart TB\n subgraph Pyramid[\"Testing Strategy\"]\n E2E[E2E Tests
Few, slow]:::red\n Integration[Adapter Integration Tests
Medium]:::orange\n Unit[Domain Unit Tests
Many, fast]:::green\n end\n\n E2E --> Integration --> Unit\n\n classDef red fill:#ff8787,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\nMost tests are fast unit tests of domain logic. Fewer tests validate adapter integration. Fewest tests verify end-to-end behavior.\n\n---\n\n# Relationship to Other Patterns\n\n### Hexagonal and Clean Architecture\n\nClean Architecture by Robert Martin is very similar:\n\n\n```mermaid\nflowchart TB\n subgraph Clean[\"Clean Architecture Layers\"]\n E[Entities]:::orange\n U[Use Cases]:::orange\n I[Interface Adapters]:::teal\n F[Frameworks & Drivers]:::primary\n end\n\n F --> I --> U --> E\n\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef primary fill:#00ceff,stroke:#000,color:#000\n```\n\n\nSame core principle: dependencies point inward. Domain at center. Infrastructure at edges.\n\n### Hexagonal and Onion Architecture\n\nOnion Architecture is another variant:\n\n\n```shell\nLayer structure (innermost to outermost):\n1. Domain Model (entities, value objects)\n2. Domain Services (business logic)\n3. Application Services (use cases)\n4. Infrastructure (adapters)\n\nSame idea: Pure domain core, infrastructure outside\n```\n\n\n### Hexagonal in Microservices\n\nEach microservice can use hexagonal internally:\n\n\n```mermaid\nflowchart TB\n subgraph Service1[\"Order Service\"]\n A1[Adapters]:::teal --> D1[Domain]:::orange\n end\n\n subgraph Service2[\"Payment Service\"]\n A2[Adapters]:::teal --> D2[Domain]:::orange\n end\n\n A1 <-->|HTTP/Events| A2\n\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n```\n\n\nServices communicate through their adapters. Domains remain isolated.\n\n---\n\n# Advantages of Hexagonal Architecture\n\n### Technology Independence\n\n\n```shell\nToday: PostgreSQL + REST\nTomorrow: MongoDB + GraphQL\n\nWhat changes: Adapters\nWhat stays: Domain logic (the valuable part)\n```\n\n\n### Testability\n\n- Test business logic without infrastructure\n- Fast, reliable unit tests\n- Easy to mock/stub secondary ports\n\n### Maintainability\n\n- Clear boundaries and responsibilities\n- Changes to infrastructure do not ripple into domain\n- Easier to understand where code belongs\n\n### Flexibility\n\n- Add new adapters without changing core\n- Support multiple interfaces (REST, CLI, events)\n- Swap implementations easily\n\n---\n\n# Disadvantages of Hexagonal Architecture\n\n### Indirection\n\n\n```shell\nSimple CRUD becomes:\nController → UseCase → Service → Repository → Database\n\nMore layers, more code to navigate.\n```\n\n\n### Boilerplate\n\n\n```shell\nFor each operation:\n- Port interface\n- Command/Query object\n- Adapter implementation\n- Mapping between layers\n\nMore files, more ceremony.\n```\n\n\n### Over-Engineering Risk\n\n\n```shell\nSimple application with hexagonal:\n- 50 files for basic CRUD\n- Team confused by structure\n- Slower development\n\nThe architecture solves problems you might not have.\n```\n\n\n### Learning Curve\n\n\n```shell\nDevelopers must understand:\n- Dependency inversion principle\n- Port/adapter concept\n- Where code belongs\n- How to test at each layer\n```\n\n\n---\n\n# When to Use Hexagonal Architecture\n\n### Good Fit\n\n\n| Scenario | Why Hexagonal Helps |\n|----------|---------------------|\n| **Complex domain** | Keep business logic pure and testable |\n| **Multiple interfaces** | Same domain, different adapters |\n| **Expected infrastructure changes** | Swap databases, cloud providers |\n| **Long-lived applications** | Investment pays off over time |\n| **High test coverage goals** | Domain easily unit tested |\n\n\n### Poor Fit\n\n\n| Scenario | Why Hexagonal Adds Overhead |\n|----------|----------------------------|\n| **Simple CRUD** | Complexity not justified |\n| **Prototype/MVP** | Speed more important than structure |\n| **Small team with time pressure** | Learning curve slows delivery |\n| **Stable, simple infrastructure** | Flexibility not needed |\n\n\n### Pragmatic Approach\n\n\n```shell\nStart simpler:\n1. Begin with basic layering\n2. Identify where boundaries matter\n3. Apply ports/adapters where valuable\n4. Don't over-engineer from day one\n\nEvolve toward hexagonal:\n- When testing becomes painful\n- When you need to change infrastructure\n- When domain complexity grows\n```\n\n\n---\n\n# Summary\n\nHexagonal architecture separates business logic from infrastructure:\n\n- **Core principle:** Dependencies point inward; domain knows nothing about adapters\n- **Ports:** Abstractions defined by the domain for input (primary) and output (secondary)\n- **Adapters:** Implementations connecting ports to specific technologies\n- **Structure:** Domain at center, adapters at edges, configuration wires them together\n- **Benefits:** Technology independence, testability, maintainability, flexibility\n- **Drawbacks:** Indirection, boilerplate, over-engineering risk, learning curve\n- **Best for:** Complex domains, multiple interfaces, expected infrastructure changes\n\nHexagonal architecture is not about system topology. It is about how you structure code within any application, whether monolith, microservice, or serverless function.","pageType":"system-design"}

Hexagonal Architecture

Ashish Pratap Singh

Get Premium