tomevault-io 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:
*Viewor*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)
Converted and distributed by TomeVault — claim your Tome and manage your conversions.