🏛️ Hexagonal Architecture
Hexagonal architecture (also called Ports and Adapters) is an architectural style that makes your application independent of frameworks, databases, UI, and external systems. It places your domain logic at the center, surrounded by “ports” (interfaces) and “adapters” (implementations). This creates a highly testable, maintainable, and flexible system.
Hexagonal architecture — definition
Section titled “Hexagonal architecture — definition”Hexagonal architecture organizes a system so that core business logic (the domain) is completely isolated from external concerns. Communication happens through ports (interfaces) and adapters (implementations). This allows you to swap databases, UIs, or external services without changing domain code.
It answers:
- How do we protect domain logic from external changes?
- How do we make the system testable and adaptable?
- How do we enforce clean boundaries?
Visual intuition
Section titled “Visual intuition”Hexagonal architecture is often drawn as a hexagon to emphasize multiple entry points (not just one UI or API).
Core concepts
Section titled “Core concepts”1. Domain
Section titled “1. Domain”The center of the architecture.
Contains business rules, entities, value objects, domain services.
No external dependencies.
2. Ports
Section titled “2. Ports”Interfaces that define how the domain communicates with the outside world.
Two types:
- Inbound ports — how external actors call the domain
- Outbound ports — how the domain calls external systems
3. Adapters
Section titled “3. Adapters”Implementations of ports.
Examples: controllers, repositories, message handlers, API clients.
4. Application core
Section titled “4. Application core”Use cases orchestrating domain logic.
Coordinates inbound/outbound ports.
How hexagonal architecture works
Section titled “How hexagonal architecture works”Inbound flow (external → domain)
Section titled “Inbound flow (external → domain)”- UI/API receives a request
- Controller calls an inbound port
- Application service executes domain logic
- Domain may call outbound ports
- Response returned to UI/API
Outbound flow (domain → external)
Section titled “Outbound flow (domain → external)”- Domain needs external data
- Calls an outbound port
- Adapter implements the port (e.g., repository)
- External system responds
- Domain continues processing
This keeps domain logic pure and independent.
Benefits of hexagonal architecture
Section titled “Benefits of hexagonal architecture”- Strong separation of concerns
- Domain purity — no framework or database leakage
- High testability — mock ports, test domain in isolation
- Replaceability — swap adapters without touching domain
- Multiple entry points — API, CLI, events, UI
- Ideal for microservices — clear boundaries and contracts
- Supports long‑term maintainability
Common mistakes
Section titled “Common mistakes”- Putting business logic in adapters
- Allowing domain to depend on infrastructure
- Creating ports that expose infrastructure details
- Over‑engineering ports for trivial use cases
- Mixing inbound and outbound responsibilities
Hexagonal vs layered architecture
Section titled “Hexagonal vs layered architecture”| Aspect | Layered | Hexagonal |
|---|---|---|
| Dependency direction | Top → bottom | Toward the domain |
| Domain purity | Medium | Very high |
| Testability | Good | Excellent |
| Flexibility | Medium | High |
| Entry points | Usually one | Many |
| Infrastructure | Bottom layer | Adapter layer |
Hexagonal architecture is stricter and more domain‑centric.
Example
Section titled “Example”A hexagonal architecture for a Daily Scrum application might look like:
Domain
Section titled “Domain”- Entities:
Task,Member,DailySession,Summary - Value objects:
TaskStatus,MemberRole - Domain services:
SummaryGenerator
Inbound ports
Section titled “Inbound ports”IGenerateDailySummaryIManageTasksISendReminder
Outbound ports
Section titled “Outbound ports”ITaskRepositoryIMemberRepositoryINotificationClientIPdfExporter
Adapters
Section titled “Adapters”-
Inbound adapters
- Blazor components
- API controllers
- Message handlers (Service Bus)
-
Outbound adapters
- PostgreSQL repository
- Azure Service Bus publisher
- PDF library implementation
- Email/SMS provider
This structure ensures your domain is clean, testable, and independent of Blazor, PostgreSQL, or Azure.
Takeaway
Section titled “Takeaway”Hexagonal architecture isolates your domain logic behind ports and adapters, making your system flexible, testable, and independent of external technologies. It is one of the strongest architectures for long‑term maintainability and aligns perfectly with clean architecture and DDD.