Conceptly
← All Concepts
πŸ”·

Hexagonal Architecture

StructureA structure that shields the core behind ports and adapters

Hexagonal Architecture places the business core in the middle and surrounds it with adapters for web, storage, messaging, or other technologies. The core depends only on ports, which are contracts for what it needs or exposes. That keeps business logic from being shaped directly by frameworks and infrastructure details.

β–ΆArchitecture Diagram

πŸ” Structure

Dashed line animations indicate the flow direction of data or requests

Why do you need it?

Even in layered systems, ORM entities, HTTP DTOs, and framework conventions often leak into the core model. Once that happens, changing storage or transport details can destabilize the very rules that should last longest. Testing also gets heavier because core behavior depends on too many technical parts.

Why did this approach emerge?

As frameworks and ORMs improved productivity, they also made it easy for technical details to spread into business code. Systems with long-lived domain rules needed a better way to keep the core stable while infrastructure kept changing. Hexagonal Architecture became one of the strongest answers to that pressure.

How does it work inside?

Inbound adapters translate requests into use-case ports, the core executes its rules, and outbound ports express what the core expects from storage or external collaborators. Adapters implement those outbound ports against databases, brokers, or APIs. The important property is the direction of dependency: infrastructure depends on the core contract, not the other way around.

Boundaries & Distinctions

Layered Architecture separates responsibilities vertically, while Hexagonal Architecture focuses on dependency direction and edge isolation. DDD says what should live in the model; Hexagonal helps keep that model from being polluted. In very simple CRUD-heavy systems, the ceremony can outweigh the benefit.

When should you use it?

It is especially useful when business rules matter, when several delivery channels or integrations must share the same core, or when fast isolated testing is important. It is common inside Modular Monoliths and Microservices alike. The key is to keep ports meaningful to use cases rather than turning them into empty abstraction ceremony.

Separating core rules from framework detailsTesting business logic without databases or brokersHiding storage, messaging, and external APIs behind clear contractsBuilding domain-centered services that may change infrastructure over time