|
| 1 | +# ADR-0003: Adopt DDD with Hexagonal Architecture across PayGuard |
| 2 | + |
| 3 | +## Status |
| 4 | +Accepted |
| 5 | + |
| 6 | +## Context |
| 7 | +PayGuard's three services (wallet, loan, collateral) each protect financial-correctness |
| 8 | +invariants that must hold regardless of which framework, database, or transport touches them — |
| 9 | +the double-entry balance rule, the LTV/liquidation threshold, the loan state machine. A few |
| 10 | +concrete pressures shaped this decision: |
| 11 | + |
| 12 | +- **Polyglot persistence per service** (JOOQ in wallet-service, JPA in loan-service and |
| 13 | + collateral-service — see ADR-0001) means the domain model cannot afford to leak persistence |
| 14 | + concerns into itself; if it did, each service's domain layer would look and behave differently |
| 15 | + just because of a technology choice. |
| 16 | +- **Invariants must be enforced in one place**, inside the aggregate, not re-implemented at every |
| 17 | + entry point (REST controller, Kafka consumer, gRPC handler) that can trigger a mutation. A |
| 18 | + hexagonal boundary is what makes "the domain doesn't know or care who's calling it" actually true. |
| 19 | +- **Testability**: domain logic (state transitions, LTV math, balance invariants) needs to be unit |
| 20 | + testable with zero infrastructure — no Testcontainers, no Spring context — which only works if |
| 21 | + the domain has no framework/persistence dependencies to begin with. |
| 22 | +- **This is a portfolio project built to demonstrate depth in backend architecture** for the EU |
| 23 | + Java market; DDD + hexagonal is the architecture pattern most directly aligned with a |
| 24 | + depth-over-breadth, strong-opinions-on-architecture positioning. |
| 25 | + |
| 26 | +## Decision |
| 27 | +Structure every PayGuard service as **DDD tactical patterns (Aggregates, Value Objects, Domain |
| 28 | +Events) inside a Hexagonal (Ports & Adapters) boundary**: |
| 29 | + |
| 30 | +- `domain` package: aggregates, value objects, domain services — no Spring, no jOOQ/JPA, no Kafka |
| 31 | + imports. |
| 32 | +- `application` package: use cases / orchestration, defining outbound ports (repository |
| 33 | + interfaces, event-publisher interfaces) that the domain layer's use cases depend on. |
| 34 | +- `adapter` package(s): inbound (REST/gRPC controllers, Kafka consumers) and outbound (jOOQ/JPA |
| 35 | + repository implementations, Kafka producers) — these depend inward on `application`/`domain`, |
| 36 | + never the reverse. |
| 37 | + |
| 38 | +CQRS is deliberately **not** adopted for now (per current architecture decisions) — the |
| 39 | +added complexity of separate read/write models isn't justified yet at this project's scale; |
| 40 | +this can be revisited per-service if a specific read pattern demands it later. |
| 41 | + |
| 42 | +## Consequences |
| 43 | + |
| 44 | +**Positive** |
| 45 | +- Domain invariants (e.g. `Transaction.post()`'s balance check, `Loan`'s state machine, ` |
| 46 | + CollateralPosition`'s LTV guard) are unit-testable in plain JUnit, no framework bootstrap needed. |
| 47 | +- Swapping jOOQ for JPA (or vice versa) in a given service is an adapter-level change; the domain |
| 48 | + and application layers are untouched. |
| 49 | +- Consistent shape across all three services makes the codebase easier to onboard teammates into |
| 50 | + and easier to narrate in an interview — the pattern doesn't change even though the persistence |
| 51 | + tech does. |
| 52 | + |
| 53 | +**Negative** |
| 54 | +- More upfront structure/ceremony (ports, adapters, mapping between domain objects and |
| 55 | + persistence records) than a simpler layered or transaction-script approach — slower to build the |
| 56 | + first version of any given feature. |
| 57 | +- Risk of over-engineering small, genuinely CRUD-like slices (e.g. a trivial lookup endpoint) |
| 58 | + with the full port/adapter ceremony when a simpler pass-through would do; needs judgment per |
| 59 | + use case rather than blind consistency. |
| 60 | +- No CQRS means read-heavy queries (e.g. a dashboard needing joined data across aggregates) will |
| 61 | + go through the same write-side domain model for now, which may need revisiting if query |
| 62 | + complexity grows. |
| 63 | + |
| 64 | +## Alternatives considered |
| 65 | +- **Simple layered architecture (Controller → Service → Repository, anemic domain model)** — |
| 66 | + rejected because it tends to let invariant-checking logic leak into service classes and get |
| 67 | + duplicated or forgotten at a second entry point. |
| 68 | +- **Full CQRS + Event Sourcing from the start** — rejected as more complexity than the current |
| 69 | + scope justifies; the append-only ledger in wallet-service already gets much of the audit benefit |
| 70 | + without a full event-sourced write model everywhere. |
0 commit comments