Bounded Contexts
This is the living domain map for PPP. It is the source of truth for the DDD-lite adoption ratified in ADR-0003. Keep it current as contexts are consolidated.
Not to be confused with Domain Structure, which describes DNS domains and subdomains. "Domain" here means a bounded context — a cohesive slice of the product with its own ubiquitous language.
Adoption is advisory and incremental: new code follows these conventions immediately; existing code is brought into line opportunistically when a feature already touches it. No big-bang git mv.
How to use this page
- Adding a feature? Find its context below and put schema, services, routers, and UI modules in that context's homes. Use the context's ubiquitous language.
- Unsure which context? Check the glossary and the open questions. If it is still ambiguous, raise it rather than guessing.
- Two concepts overlapping? Cross-context access goes through an explicit boundary (a service call), never an ad-hoc import into another context's internals.
The context map
Eleven ratified contexts. "Owns today" lists the real folders/symbols currently in each context; some live under legacy names pending consolidation (flagged).
1. Identity & Profile
Who the user is: account, profile, medical registration (GMC/AHPRA), supervisors, job role, sign-up and onboarding.
| Layer | Owns today |
|---|---|
| Schema | users, auth, userRegistrations, userSupervisors, jobTitles, pppJobRoleHistory, speciality, ahpraValidationCache |
| Services | auth, authService, userProfileService, userRegistrationService, userTypeClassification, jobRoleHistoryService, specialityResolutionService, specialistStatusService, gmcRegistrantService, ahpraRegistrantService, onboardingService, pendingAccountsService |
| Procedures | auth, createUserProfile, getCurrentUser, getUserProfile, updateUserProfile, users, listUsers, getAllUsers, getAllUserIds, getUsersForPicker, userReadProcedures, addressHistory, ahpra, gmc, onboarding, pendingAccounts, userRegistrations |
| Modules (FE) | MyProfile, Signup, AcceptInvite, AwaitingActivation, Users |
Allowed dependencies: none inbound-only (most contexts depend on Identity for the current user). Identity must not import from feature contexts.
2. Passport
The PPP Passport — a doctor-owned, shareable credentials and compliance record: documents, immunisations, mandatory training, registrations, visa, indemnity, medical degree, and the share/review flow.
| Layer | Owns today |
|---|---|
| Schema | pppPassport, pppHrPassport (legacy symbol; table ppp_hr_passports), addressHistory (table address_history; file previously misnamed hrPassportCompliance.ts — no such table ever existed, renamed #10541), medicalPassportDocuments, medicalPassportShareLinks, mandatoryTrainingSeed |
| Services | pppPassportService, pppPassportMedicalDegreeService, pppPassportReviewService, passportImmunisationService, passportRegistrationService, passportTrainingService, visaService, indemnityService, hrPassportService (legacy), certificateService, certificateGenerationService |
| Procedures | hrPassport (legacy), medicalPassport |
| Modules (FE) | PppPassport, MedicalPassport, HrPassport (legacy), VerifyTraining |
Consolidation target (issue #8252): collapse HrPassport / MedicalPassport into one Passport module; delete the orphaned MyProfile/components/HrPassport.tsx; collapse routes /passport + /ppp-passport into /ppp-passport; rename pppHrPassport / ppp_hr_passports to passport language via migration when safe.
3. CPD
Continuing Professional Development: activities, plans, categories, classes, providers, specialist high-level requirements (HLSR/MCR), external approver flow, the resource library, and competency/cadence targets.
| Layer | Owns today |
|---|---|
| Schema | cpdPlans, cpdPlanActivities, cpdPlanClasses, cpdPlanTemplates, cpdActivities, cpdActivitiesList, cpdActivityCategory, cpdActivitySpeciality, cpdActivityProvider, cpdActivityTypeSettings, cpdCategories, cpdClasses, cpdUserActivities, cpdEndOfYear, cpdHlsrAttestations, cpdApproveTokenIssued, cpdReminderSettings, cpdAphraSettings, cpdAphraPreNotification, activities, competencyTargets, smartGoals, mcrAssessorResponses, snomedWbaMappings, resources, resourceClicks, resourceBookmarks, resourceHistory, resourceCompletions, keywords, faqPosts, externalApproverCodes, meetings |
| Services | cpdActivityService, cpdCategoryService, cpdClassService, cpdPlanService, cpdPlanNudgeService, cpdPlanSuggestionService, cpdPlanTemplateService, cpdHlsrAttestationService, cpdProviderVettingService, cpdUserActivities, activitiesService, competencyTargetService, cadenceTargetService, multiClinicianCreditService, pdpGenerationService, mcrService, meetingCpdConfigService, meetingsService, externalApproverCodeService, resourceService, resourceLibraryService, resourceClickService, snomedLookupService, snomedLookup |
| Procedures | cpdActivities, cpdCategories, cpdClasses, cpdHlsrAttestation, cpdPlan, cpdPlanNudge, cpdPlanSuggestions, cpdPlanTemplates, cpdReminders, cpdUserActivities, createCpdPlan, getCpdPlanForCurrentUser, getCpdPlanForUserId, updateCpdPlanForCurrentUser, searchCpdActivitiesByCategory, activities, approveCpdActivity, externalApproverAuth, competencyTargets, cadenceTarget, mcr, meetingCpdConfig, resource, resourceClicks, resourceLibrary |
| Modules (FE) | CPDHomeV2, CPDActivities, CPDActivitiesList, CPDPlans, MakeCpdPlan, CPDProviderFramework, CPDSpecialistAreas, ExternalApprove, Guide |
4. Wellness
Wellbeing: questionnaires (WHO-5/WWQ), readiness scoring, reflection quality, and proactive coaching prompts/nudges.
| Layer | Owns today |
|---|---|
| Schema | wellness, proactivePromptConfig, proactivePromptLog |
| Services | wellnessService, proactiveNudgesService, proactivePromptService, reflectionQualityService |
| Procedures | wellness, proactiveNudges, proactivePrompts |
| Modules (FE) | wellness/WellnessScore, wellness/EndOfYearReflection |
5. Logbook
Surgical logbook: cases, procedures master data, and external logbook API tokens.
| Layer | Owns today |
|---|---|
| Schema | surgicalCase, procedures, logbookApiTokens |
| Services | surgicalCaseService, logbookService, logbookApiTokenService |
| Procedures | logbook, logbookApiTokens |
| Modules (FE) | LogbookCase, LogbookReport |
6. Timesheet & Attendance
Work hours and presence: timesheets, batches, geofence events/preferences, and workplace locations.
| Layer | Owns today |
|---|---|
| Schema | timesheets, timesheetBatches, timesheetBatchStatusHistory, geoFenceEvents, geoFencePreferences, workplaceLocations |
| Services | timesheetServices, timesheetBatchServices, timesheetNudgeService, attendanceService, geoFenceEventService, geoFencePreferencesService, geocodingService, workplaceLocationsService |
| Procedures | timesheets, timesheetNudge, attendance, geoFenceEvent, geoFencePreferences, workplaceLocations |
| Modules (FE) | Timesheet, Attendance |
7. Payments & Subscriptions
Stripe billing, account type/entitlement, and payment banners. Most billing state currently lives as fields on the user account rather than a dedicated schema group (see open questions).
| Layer | Owns today |
|---|---|
| Schema | (no dedicated schema group yet — billing fields live on users) |
| Services | paymentService, paymentBannerService |
| Procedures | payments, paymentBanner |
| Modules (FE) | Billing, PlansAndPricing, CompletePayment |
8. Reports & Export
Generated reports and exports: PDF jobs, export share links, exportable reports, multi-feature/multi-consultant reports, and the import wizard.
| Layer | Owns today |
|---|---|
| Schema | pdfExportJobs, exportLinks |
| Services | reportsService, reportPdfService, reportEvidenceService, multiFeatureReportService, pdfJobService, exportLinkService, importWizardService, importExecutionService |
| Procedures | reports, exportableReports |
| Modules (FE) | Reports, MultiConsultantReport, MSFReport (appraisal report surface — see #11 and open question #4) |
9. Admin & Org
Tenancy and administration: hospitals, tenants, org dashboard, hospital admin roles, super admin, settings, instance config, system prompts, audit, work queue, roadmap, support, and bug reports.
| Layer | Owns today |
|---|---|
| Schema | hospitals, hospitalTenants, hospitalAdmins, hospitalFeatureToggles, hospitalHealthServices, hospitalEnterprise, pppHospitals, pppHospitalMembership, userHospitals, organisations, orgDashboardOkrConfig, orgDashboardSectionSummaryPrefs, settings, systemSettings, instanceConfig, systemPrompts, superAdminTodos, auditLog, auditTrail, auditArchiveBatches, auditField, todoSnoozes, roadmapMilestones, ocrHospitalAliases |
| Services | hospitalAdminService, hospitalAdminRosterService, hospitalExecutiveAdminService, hospitalFeatureToggleService, hospitalInsightsService, hospitalInviteService, hospitalLookup, hospitalManagementService, hospitalMembershipService, hospitalStaffService, org-dashboard, superAdminService, settingsServices, instanceConfigService, systemPromptsService, auditLogService, auditTrailService, accessControl, roadmap, todoListService, workQueueService, ocrHospitalMatchService, ocrPrivacyService, bugReportService, supportServices, storageCleanupService, imageService, workplaceLocationsService |
| Procedures | hospitalAdmin, hospitalExecutiveAdmin, hospitalInvite, hospitalLookup, hospitalManagement, hospitalMembership, hospitalStaff, hospitalSuperAdmin, org-dashboard, superAdmin, settings, instanceConfig, systemPrompts, auditLog, auditTrail, accessControl, roadmap, todoList, workQueue, support, bugReport, ocrHospitalMatch, ocrPrivacy, storage, userAssignedHospitals, getUserAssignedHospitals |
| Modules (FE) | Admin, HospitalAdmin, HospitalExecutiveAdmin, HospitalStaff, HospitalSuperAdmin, OrganisationalInsights, Settings, WorkQueue, Support, AuditTrail, UniversalSearch, PPPDashboard |
10. Notifications
Delivery: in-app and push notifications, scheduling, device tokens, and preferences.
| Layer | Owns today |
|---|---|
| Schema | notifications, userNotifications, notificationPreferences |
| Services | notificationService, scheduledNotificationService, userNotificationTokenService |
| Procedures | notifications, userNotificationToken |
| Modules (FE) | Notifications, UnifiedInbox |
11. Appraisal & Feedback
Multi-source assessment and the annual appraisal portfolio: the appraisal workflow (state machine, evidence pack, reminders), 360-degree feedback, MSF (Multi-Source Feedback) and MCR (Multiple Consultant Report), Work-Based Assessments (WBA: CBD, CEX, DOPS), and the appraisal-specific compliance/program forms. This context aggregates evidence from other contexts (CPD plans, WBA, Wellness, reflections) into an appraisal portfolio, but it owns its own workflow, language (appraiser, evidence pack, 360, MSF, MCR, WBA), and assessment schema.
| Layer | Owns today |
|---|---|
| Schema | appraisalWorkflow, ppp360, ppp360reviews, ppp360reviewers, programForms, complianceFormSubmissions |
| Services | appraisalWorkflowService, appraisalAggregationService, appraisalReminderService, ppp360Service, complianceFormService, programFormService |
| Procedures | appraisalWorkflow, appraisalReminders, ppp360, complianceForms, programForms |
| Modules (FE) | AppraisalForm, MSF, WBA, PPP360Reviews, Reviews |
WBA constants (packages-shared/ppp/src/constants/wba.ts, wba-role-config.ts) and the appraisals/WBA UI under instances/ppp/src/forms/ (WBAForm, WBAConsultantForm) belong to this context (see the appraisals-wba spec, capability "Professional Development & Evidence").
Not in this context — the generic record-linking / forms engine.relatedFormService / relatedForms (a polymorphic inputRecordId → outputRecordId + type join), formPromptsService / formPrompts, and relatedForm / formPrompts procedures are cross-cutting infrastructure, not appraisal-specific: relatedForms.type is an open string spanning cpdUserActivity, wba, reflection, and ppp360, and the engine is consumed by CPD (activitiesService, cpdUserActivities), Logbook (logbookService), and MCR as well as appraisal. These stay in services/shared/ (see Conventions) and are invoked by any context that needs to link a form/output record to a source record.
Evidence aggregation goes through context boundaries.appraisalAggregationService currently reads cpdPlans, wba, wellness, ppp360, and reflection schema directly to build the evidence pack. As #8253 consolidates, those cross-context reads should move behind owning-context service calls (CPD / Wellness / Logbook), not direct table access — the aggregation service is a consumer of those contexts, and none of them depend back on Appraisal.
Ubiquitous-language glossary
The canonical term is on the left. Use it in code, routes, UI copy, and docs. Legacy aliases are kept only for the not-yet-renamed symbols listed.
| Canonical term | Means | Do not use / legacy aliases |
|---|---|---|
| PPP Passport | The doctor-owned, shareable credentials + compliance record (documents, immunisations, training, registrations, visa, indemnity). | "HR Passport" (user-facing rename #5623), "Medical Passport". Legacy symbols still in tree: pppHrPassport, table ppp_hr_passports, hrPassportService, module HrPassport, route /passport. |
| Job Role | A user's role/grade at a hospital over time (ppp_job_role_history). | "grade" as a standalone concept — grade is an attribute of a Job Role, historically on pppHrPassport. |
| Marketing admin | The admin surface of the marketing site (/news-admin and its /api/*/admin/* functions): news review and the waitlist list. Runs on Cloudflare, no PPP accounts. | Calling it "the admin console" or "Super Admin" (those are the PPP app's). |
| PPP admin console | The PPP app's role-based admin for hospitals, tenants and staff (context 9, Admin & Org). | Using it for the marketing news admin. |
| Bounded context | A cohesive product slice owning its schema/services/routers/UI and language. | "module" (frontend folder) and "domain" (overloaded — also DNS) when you mean a context. |
| Context boundary | The explicit seam (a service call) through which one context invokes another. | Direct imports into another context's internals. |
| Identity | The current user's account, profile, and registration. | "user management" when you mean the Identity context vs the Admin user-list screens. |
| CPD activity vs CPD plan | An activity is a logged/credited item; a plan is the yearly target structure. | Using "CPD" alone where the distinction matters. |
| Geo-fence ENTER/EXIT event | A geo_fence_events row recording the mobile app crossing a hospital's geofence boundary (eventType: 'entry' | 'exit'). | Shortening to "entry"/"exit" as a noun on its own — always say "geo-fence entry event"/"geo-fence exit event" (or ENTER/EXIT) so it is never confused with a timesheet record. |
| Timesheet / timesheet record | A timesheets table row — a logged (or auto-detected) work shift. | "entry" or "timesheet entry" as a noun for a row — retired (#11227); it collided with geo-fence entry events. UI copy/labels may still say "timesheet entry" as a feature name (e.g. a form title); code and comments referring to the row itself use "timesheet"/"timesheet record". |
status: 'draft' | The literal TimesheetStatus enum value (see TIMESHEET_STATUS_TRANSITIONS) — a timesheet the doctor has not yet submitted. | Using "draft" loosely to mean "not yet closed by a geo-fence exit" — that state is the open shift below, and is independent of status. |
| Open shift (a.k.a. unclosed shift placeholder) | A timesheet auto-created at geo-fence ENTRY whose endTime - startTime still equals the sentinel placeholder duration — detected by isGeoFenceArrivalPlaceholder, never by status. | Calling this a "draft" — a doctor can save an unrelated field on it (moving nothing about its open/closed state) without ever touching status. |
Conventions
These apply to new code now and to existing code when a change already touches it.
Backend (api/backend-ppp/)
Target layout groups each layer under a context folder:
src/services/{context}/...
src/routers/procedures/{context}/...
packages-shared/ppp/src/schema-groups/{context}/...- One context folder per bounded context; the context name matches this map.
- Cross-context calls go through a service, never a deep import into another context's procedures or internal helpers.
- Shared, context-free helpers stay in
services/shared/. The generic record-linking / forms engine (relatedFormService,formPromptsService) is one of these: it links a form/output record to a source record across CPD, Logbook, MCR, and Appraisal, so it is owned by no single context (#8400). - Do not add new top-level flat
services/xxxServicefolders for a concept that belongs to an existing context — nest it under that context.
Frontend (instances/ppp/src/modules/)
- One
modules/{context}/per bounded context. Do not create a second module for the same domain (theHrPassport/MedicalPassport/PppPassportsplit is the anti-pattern this rule prevents). - Module and route names use the ubiquitous language (
PppPassport,/ppp-passport). - Cross-context UI reuse goes through shared components in
src/components/, not by importing another module's internals.
Schema barrel (packages-shared/ppp/src/schema.ts)
- Keep the single barrel (Drizzle and consumers import by symbol name), but group the
export *lines by context with a section header comment per context, in the same order as this map. - Align table/symbol names with the ubiquitous language, via migration, when a rename is safe (see the schema-change rules in
CLAUDE.md).
Cross-context boundary rules
- A context may depend on Identity & Profile (for the current user) and on Notifications (to send) without ceremony.
- Any other cross-context dependency should be a deliberate service call and worth a second look in review — prefer composition at the router/page level over contexts reaching into each other.
Open questions / unresolved boundaries
Recorded rather than guessed. Resolve before the relevant consolidation move.
- Appraisal & Feedback — RESOLVED (#8400): promoted to the eleventh context (Option A), with the generic forms engine kept in
services/shared/. The appraisal/feedback cluster is a cohesive product area with its own ubiquitous language (appraiser, evidence pack, 360, MSF, MCR, WBA, Yearly Appraisal) and its own assessment schema and workflow — it is now context 11. It is not folded into CPD: the dependency runs one way (appraisalAggregationServicereads CPD/Wellness/WBA evidence; nothing in CPD depends on appraisal), and the Yearly Appraisal "crossover" Matt describes (#8178 — the annual CPD-plan review rolling into the appraisal + PDP) is a composition flow across two contexts, not a reason to merge them. The split-into-Admin&Org half of Option B was rejected for the appraisal-specific forms (programForms,complianceFormSubmissions) — they are appraisal config, not org admin — but its insight was kept: the truly generic record-linking/forms engine (relatedFormService/relatedForms,formPromptsService/formPrompts) is cross-cutting infrastructure used by CPD, Logbook, and MCR too, so it stays inservices/shared/rather than being owned by any single context. This unblocks #8253 / #8254: appraisal files consolidate under a singleappraisalcontext folder, and the shared forms engine moves toshared/. Decision recorded in ADR-0004. Engineering-ratified and reversible if a senior architect objects. - Payments has almost no dedicated schema — billing state lives on
users. Decide whether Payments warrants its own schema group or stays a thin service-only context over Identity data. - Hospital membership straddles Identity and Admin & Org.
userHospitals/pppHospitalMembershipare listed under Admin & Org, but they are read on nearly every Identity flow. Confirm ownership and the read path. - Reports vs the owning context.
LogbookReportandMSFReportare report surfaces for other contexts (Logbook and the new Appraisal & Feedback context respectively). Decide whether report UIs live in Reports & Export or in the owning context with shared export plumbing. Until resolved,MSFReportis listed under Reports & Export with a cross-reference; #8400 did not pre-empt this call. - Dashboards (
PPPDashboard,CPDHomeV2) aggregate across contexts. They are composition surfaces (per-context home screens) that own no domain logic of their own. The dashboard fragmentation was resolved in #8432: the rollback-only V1 module and an orphanedDashboardmodule were retired and the canonical module renamed to a singlePPPDashboardserved at/ppp-dashboard.
Not part of the context model
modules/DesignSystem and modules/Development are internal developer tooling (component gallery, dev utilities), not product domains, so they sit outside the bounded-context model by design.
The marketing site — and its admin — sit outside the context model too (#12424)
instances/marketing/ is a separate deployable (Cloudflare Pages + Pages Functions + KV), not a bounded context of the PPP app. It has its own admin, and that admin is deliberately not part of context 9 (Admin & Org):
| Marketing admin | PPP admin console (context 9, #11220) | |
|---|---|---|
| Runs on | Cloudflare Pages Functions + KV (PPP_NEWS, PPP_WAITLIST) | The PPP app: React SPA → tRPC backend → PostgreSQL |
| Code | instances/marketing/src/landing/pages/NewsAdmin.tsx, instances/marketing/functions/api/news/admin/*, functions/api/waitlist/admin/list.ts | instances/ppp/src/modules/admin-org/**, api/backend-ppp/src/routers/procedures/admin-and-org/** |
| Manages | Public-site content: news articles (review, approve/reject, add by URL) and the waitlist list | Hospitals, tenants, org roles, staff, super-admin settings |
| Access | Cloudflare Access sign-in and a shared bearer token (NEWS_ADMIN_TOKEN) — the marketing site has no user accounts | PPP accounts and role-based permissions |
| Guide | Marketing News Review Guide | Admin/Super-Admin console docs |
Rules
- No shared runtime. Marketing admin code must not import from
instances/ppp/orapi/backend-*, and must not call the PPP backend. The PPP app must not read or write the marketing KV namespaces. The only code the marketing site takes from the PPP workspace is@ppp-org/ppp/constants(pure price constants for the public pages), never anything admin-related. - Why. The PPP app is not in production (as of 2026-09-22), so the marketing site has to be able to run — and be administered — entirely without it. Matt agreed to two admins on the 2026-09-22 call.
- Two logins, on purpose. Do not merge the two surfaces, or route marketing content through the PPP backend, without a new decision. Whether they should converge once the app is live is open and undecided.
Verified 2026-09-23: nothing under instances/marketing/src or functions imports from the app or backend (grep for instances/ppp, api/backend, packages-shared outside @ppp-org/ppp/constants). No automated guard enforces rule 1 yet.
Change log
| Date | Change |
|---|---|
| 2026-06-09 | Initial map, glossary, and conventions ratified (ADR-0003, #8251). |
| 2026-06-22 | Open question #1 resolved: Appraisal & Feedback promoted to context 11; generic forms engine kept in services/shared/ (ADR-0004, #8400). |
| 2026-09-23 | Marketing site and its admin recorded as outside the context model, with a boundary table and rules (#12424). Glossary gains Marketing admin / PPP admin console. |