ADR-0003: Adopt domain-based (DDD-lite) design — bounded contexts
Status
Accepted
Context
PPP's backend and frontend have grown organically. Services, routers, schema groups, and React modules are largely flat and feature-named rather than organised around bounded contexts, and the same domain is often split across several names. Concrete smells found while shipping the Job Role feature (#8086–#8088), confirmed by inspection in #8250:
- Orphaned code —
instances/ppp/src/modules/MyProfile/components/HrPassport.tsxis rendered nowhere; it was retired when the passport moved to its own page (#6411) but never deleted. - Fragmented Passport context — schema groups
pppHrPassport+pppPassport; frontend modulesHrPassport,PppPassport,MedicalPassport, plus passport bits insideMyProfile; dual live routes/passportand/ppp-passport. - Naming drift — "HR Passport" became "PPP Passport" as a user-facing rename (#5623), but the table is still
ppp_hr_passportsand the symbol ispppHrPassport. The ubiquitous language is inconsistent. - Flat structure —
packages-shared/ppp/src/schema.tsre-exports ~94 schema groups in one flat list;api/backend-ppp/src/services/androuters/procedures/are flat (~100+ feature-named folders each), and related data attributes land in different places (gradeonpppHrPassportvs the newppp_job_role_history).
This makes the codebase harder for both humans and AI agents to navigate, and it is where most "where does this go?" and accidental-duplication mistakes come from.
Decision
Adopt domain-based (DDD-lite) design across PPP: organise the backend and frontend around explicit bounded contexts sharing a ubiquitous language, so each context owns its schema, services, routers, and UI modules.
The ratified contexts, the ubiquitous-language glossary, and the folder/naming conventions live in a single living reference: Bounded Contexts. That page — not this ADR — is the source of truth and is updated as contexts are consolidated. This ADR records why and how we adopt the approach.
Adoption is governed by three principles:
- Advisory + incremental — no big-bang rewrite. Each follow-up move is an independently shippable, behaviour-preserving change that preserves type safety, tenant isolation, and test coverage. A mass
git mvwould cascade DIRTY across every open PR — the exact failure mode the fragment conventions (#5273, #6509, #8010) exist to avoid — so it is explicitly out of scope. - Ubiquitous language first. Agree the names before moving files. The glossary is authoritative; new code uses the canonical term (for example PPP Passport, never "HR Passport" or "Medical Passport").
- Document the map. The context map is kept current as the navigational index for humans and AI agents.
How adoption proceeds
- New code follows the conventions immediately (right context folder, right module name, canonical language).
- Existing code is consolidated opportunistically — when a feature already touches a context, bring that context's files into line as part of the same change, rather than scheduling a separate mass move.
- The two large reorganisation issues (#8253 backend, #8254 frontend) remain open as standing guidance, not scheduled big-bang work.
This sequencing was chosen in the #8250 deep dive (Option A): land the map now, enforce on new code, consolidate opportunistically.
Consequences
Positive
- One obvious home per concept; "where does this go?" has a documented answer.
- The map doubles as onboarding and AI-agent navigation context.
- Naming drift is resolved at the language level before any risky renames.
Negative / costs
- The map can drift from the code if not maintained; consolidation is gradual, so for a while the docs describe the target while the tree is mid-migration. The map marks each context's current-vs-target state to manage this.
- Some boundaries are genuinely ambiguous (see the open questions on the map, e.g. Appraisal & Feedback as a possible eleventh context). These are recorded rather than forced.