ADR-006: IDesign Method for Service Internals¶
Status: Accepted Date: 2026-03-09
Context¶
Need a consistent internal architecture for all .NET services. Must be simple enough for AI agents to follow, enforce separation of concerns, and make testing easy.
Options Considered¶
| Option | Pros | Cons |
|---|---|---|
| IDesign (4 layers) | Clear volatility ordering, pure engine layer, 1:1 resource access, proven method | Less well-known than Clean Architecture |
| Clean Architecture (Onion) | Popular, well-documented | More abstraction layers, "clean for the sake of clean" |
| Vertical Slices | Feature-focused, less ceremony | Cross-cutting concerns duplicated, harder for AI to follow patterns |
| No enforced structure | Fast to start | Degrades quickly, inconsistent across services |
Decision¶
Use IDesign method (Juval Löwy / "Righting Software") for all service internals, combined with Clean Architecture dependency inversion.
Rationale¶
- Volatility-based decomposition. Clients change most often, Resource Access changes least. This maps directly to where bugs cluster and where AI agents spend most time.
- Pure Engine layer. Business rules have zero I/O dependencies. Unit testing is trivial — no mocks needed. AI agents write engines confidently because there are no side effects to reason about.
- 1:1 Resource Access. Each external system has exactly one accessor. No scattered database calls. Easy to swap implementations (e.g., move from Valkey to Redis, or PostgreSQL to Cosmos).
- MediatR as the glue. Managers are MediatR handlers. Clients dispatch via
IMediator.Send(). This creates a uniform pattern AI agents can follow across all services. - Consistency across 8 services. Every service follows the same 4-project structure. An agent that learns the pattern in
tablez-reservationcan immediately work ontablez-guest.
Consequences¶
- Four projects per service (Api, Managers, Engines, ResourceAccess) + Tests. More projects than minimal, but each is small and focused.
- Strict dependency rules: Api → Managers only, Managers → Engines + ResourceAccess, Engines → nothing, ResourceAccess → nothing internal.
- New team members must understand the 4-layer model before contributing.