ADR 2: Hexagonal Ring Layering and Dependency Isolation
Summary
Strict layered architecture: adapters > application > ports > domain.
Context
In complex event sourcing frameworks, business logic frequently becomes coupled to database models, broker drivers, or telemetry frameworks. Prior refactoring waves established ring layering contracts to keep pure domain invariants isolated from infrastructure.
Decision
- Ring dependency order is strictly enforced:
adaptersoverapplicationoverportsoverdomain. domainandportsmust never importobservabilityor infrastructure technologies.- Inner rings must never import the
testingtoolkit. - Enforced automatically in CI via
import-lintercontracts.
Consequences
- Domain models and ports remain 100% portable with zero vendor coupling.
- Swapping storage or messaging adapters requires zero changes to domain business logic.
- Modular architectural boundaries prevent dependency spaghetti.