lexler/hexagonal-architecture

Hexagonal Architecture

The Core Decision Rule

To decide if something belongs inside or outside the hexagon, ask:

"Does it do I/O or run out-of-process?"

• No → Inside the hexagon (domain or application layer)
• Yes → Outside (adapter)

Critical: Consider ALL dependencies. A component's dependencies disqualify it even if the component itself doesn't do I/O. If it depends on Spring, a database driver, or any framework—it's outside.

Layer Responsibilities

Common misconception: The hexagon is NOT just the domain. The hexagon contains both domain AND application layers. Adapters sit outside.

┌─────────────────────────────────────────┐
│           ADAPTERS (outside)            │
│  Web, CLI, Database, External APIs      │
│  ┌───────────────────────────────────┐  │
│  │     APPLICATION SERVICES          │  │
│  │  ┌─────────────────────────────┐  │  │
│  │  │         DOMAIN              │  │  │
│  │  └─────────────────────────────┘  │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘
        Dependencies flow INWARD only

Domain — Business constraints (what CAN happen). Contains Entities, Value Objects, Domain Services.

Application — Orchestration (HOW things happen). Contains Use Cases, Application Services.

Adapters — Translation to/from external world. Contains Controllers, Repositories, API clients.

Domain defines ports (interfaces). Adapters implement them.

Naming Conventions

• Display/response: *View or *Response → MemberView, OrderResponse
• Incoming request: *Request → CreateMemberRequest
• Database entity: *Dbo → MemberDbo
• Domain → DTO: static from(domain) → MemberView.from(member)
• DTO → Domain: as*() method → request.asMember()

Anti-Patterns

Brittle Interfaces

register(username, password)  // Breaks when email required

Use wrapper objects that can evolve without breaking signatures.

Domain Scope Pollution

Third-party types (GoogleUser, StripePayment) leaking into domain. Keep external types in adapters; map to domain types at the boundary.

Use-Case Interdependencies

Use cases calling other use cases creates coupling. Each use case should be self-contained, orchestrating domain objects directly.

Anemic Domain

Entities as data bags with logic scattered in services. Business rules belong IN entities and value objects.

Premature Database Design

Designing schema before domain model. Domain model comes first; database adapter maps to it.

Over-Complicated Adapters

Adapters adding logic beyond translation. Adapters should be thin—just implement the port interface.

Testing Strategy

• Domain: Unit tests, no doubles needed (pure logic)
• Application: Unit tests with port doubles (fake repositories, stub notifiers)
• Adapters: Integration tests against real infrastructure (real database, real HTTP)

Ports give clean seams for test doubles. Test the domain exhaustively with fast unit tests; test adapters against real infrastructure sparingly.

When NOT to Use

• Small/simple projects, especially CRUD-based apps (overhead not worth it)