Skip to content

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.tsx is 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 modules HrPassport, PppPassport, MedicalPassport, plus passport bits inside MyProfile; dual live routes /passport and /ppp-passport.
  • Naming drift — "HR Passport" became "PPP Passport" as a user-facing rename (#5623), but the table is still ppp_hr_passports and the symbol is pppHrPassport. The ubiquitous language is inconsistent.
  • Flat structure — packages-shared/ppp/src/schema.ts re-exports ~94 schema groups in one flat list; api/backend-ppp/src/services/ and routers/procedures/ are flat (~100+ feature-named folders each), and related data attributes land in different places (grade on pppHrPassport vs the new ppp_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:

  1. 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 mv would 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.
  2. 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").
  3. 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.

References ​

Internal documentation — org members only