Skip to content

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.

LayerOwns today
Schemausers, auth, userRegistrations, userSupervisors, jobTitles, pppJobRoleHistory, speciality, ahpraValidationCache
Servicesauth, authService, userProfileService, userRegistrationService, userTypeClassification, jobRoleHistoryService, specialityResolutionService, specialistStatusService, gmcRegistrantService, ahpraRegistrantService, onboardingService, pendingAccountsService
Proceduresauth, 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.

LayerOwns today
SchemapppPassport, 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
ServicespppPassportService, pppPassportMedicalDegreeService, pppPassportReviewService, passportImmunisationService, passportRegistrationService, passportTrainingService, visaService, indemnityService, hrPassportService (legacy), certificateService, certificateGenerationService
ProcedureshrPassport (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.

LayerOwns today
SchemacpdPlans, 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
ServicescpdActivityService, cpdCategoryService, cpdClassService, cpdPlanService, cpdPlanNudgeService, cpdPlanSuggestionService, cpdPlanTemplateService, cpdHlsrAttestationService, cpdProviderVettingService, cpdUserActivities, activitiesService, competencyTargetService, cadenceTargetService, multiClinicianCreditService, pdpGenerationService, mcrService, meetingCpdConfigService, meetingsService, externalApproverCodeService, resourceService, resourceLibraryService, resourceClickService, snomedLookupService, snomedLookup
ProcedurescpdActivities, 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.

LayerOwns today
Schemawellness, proactivePromptConfig, proactivePromptLog
ServiceswellnessService, proactiveNudgesService, proactivePromptService, reflectionQualityService
Procedureswellness, proactiveNudges, proactivePrompts
Modules (FE)wellness/WellnessScore, wellness/EndOfYearReflection

5. Logbook ​

Surgical logbook: cases, procedures master data, and external logbook API tokens.

LayerOwns today
SchemasurgicalCase, procedures, logbookApiTokens
ServicessurgicalCaseService, logbookService, logbookApiTokenService
Procedureslogbook, logbookApiTokens
Modules (FE)LogbookCase, LogbookReport

6. Timesheet & Attendance ​

Work hours and presence: timesheets, batches, geofence events/preferences, and workplace locations.

LayerOwns today
Schematimesheets, timesheetBatches, timesheetBatchStatusHistory, geoFenceEvents, geoFencePreferences, workplaceLocations
ServicestimesheetServices, timesheetBatchServices, timesheetNudgeService, attendanceService, geoFenceEventService, geoFencePreferencesService, geocodingService, workplaceLocationsService
Procedurestimesheets, 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).

LayerOwns today
Schema(no dedicated schema group yet — billing fields live on users)
ServicespaymentService, paymentBannerService
Procedurespayments, 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.

LayerOwns today
SchemapdfExportJobs, exportLinks
ServicesreportsService, reportPdfService, reportEvidenceService, multiFeatureReportService, pdfJobService, exportLinkService, importWizardService, importExecutionService
Proceduresreports, 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.

LayerOwns today
Schemahospitals, hospitalTenants, hospitalAdmins, hospitalFeatureToggles, hospitalHealthServices, hospitalEnterprise, pppHospitals, pppHospitalMembership, userHospitals, organisations, orgDashboardOkrConfig, orgDashboardSectionSummaryPrefs, settings, systemSettings, instanceConfig, systemPrompts, superAdminTodos, auditLog, auditTrail, auditArchiveBatches, auditField, todoSnoozes, roadmapMilestones, ocrHospitalAliases
ServiceshospitalAdminService, 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
ProcedureshospitalAdmin, 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.

LayerOwns today
Schemanotifications, userNotifications, notificationPreferences
ServicesnotificationService, scheduledNotificationService, userNotificationTokenService
Proceduresnotifications, 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.

LayerOwns today
SchemaappraisalWorkflow, ppp360, ppp360reviews, ppp360reviewers, programForms, complianceFormSubmissions
ServicesappraisalWorkflowService, appraisalAggregationService, appraisalReminderService, ppp360Service, complianceFormService, programFormService
ProceduresappraisalWorkflow, 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 termMeansDo not use / legacy aliases
PPP PassportThe 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 RoleA 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 adminThe 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 consoleThe PPP app's role-based admin for hospitals, tenants and staff (context 9, Admin & Org).Using it for the marketing news admin.
Bounded contextA 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 boundaryThe explicit seam (a service call) through which one context invokes another.Direct imports into another context's internals.
IdentityThe 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 planAn activity is a logged/credited item; a plan is the yearly target structure.Using "CPD" alone where the distinction matters.
Geo-fence ENTER/EXIT eventA 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 recordA 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:

text
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/xxxService folders 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 (the HrPassport / MedicalPassport / PppPassport split 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.

  1. 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 (appraisalAggregationService reads 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 in services/shared/ rather than being owned by any single context. This unblocks #8253 / #8254: appraisal files consolidate under a single appraisal context folder, and the shared forms engine moves to shared/. Decision recorded in ADR-0004. Engineering-ratified and reversible if a senior architect objects.
  2. 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.
  3. Hospital membership straddles Identity and Admin & Org. userHospitals / pppHospitalMembership are listed under Admin & Org, but they are read on nearly every Identity flow. Confirm ownership and the read path.
  4. Reports vs the owning context. LogbookReport and MSFReport are 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, MSFReport is listed under Reports & Export with a cross-reference; #8400 did not pre-empt this call.
  5. 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 orphaned Dashboard module were retired and the canonical module renamed to a single PPPDashboard served 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 adminPPP admin console (context 9, #11220)
Runs onCloudflare Pages Functions + KV (PPP_NEWS, PPP_WAITLIST)The PPP app: React SPA → tRPC backend → PostgreSQL
Codeinstances/marketing/src/landing/pages/NewsAdmin.tsx, instances/marketing/functions/api/news/admin/*, functions/api/waitlist/admin/list.tsinstances/ppp/src/modules/admin-org/**, api/backend-ppp/src/routers/procedures/admin-and-org/**
ManagesPublic-site content: news articles (review, approve/reject, add by URL) and the waitlist listHospitals, tenants, org roles, staff, super-admin settings
AccessCloudflare Access sign-in and a shared bearer token (NEWS_ADMIN_TOKEN) — the marketing site has no user accountsPPP accounts and role-based permissions
GuideMarketing News Review GuideAdmin/Super-Admin console docs

Rules

  1. No shared runtime. Marketing admin code must not import from instances/ppp/ or api/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.
  2. 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.
  3. 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 ​

DateChange
2026-06-09Initial map, glossary, and conventions ratified (ADR-0003, #8251).
2026-06-22Open question #1 resolved: Appraisal & Feedback promoted to context 11; generic forms engine kept in services/shared/ (ADR-0004, #8400).
2026-09-23Marketing site and its admin recorded as outside the context model, with a boundary table and rules (#12424). Glossary gains Marketing admin / PPP admin console.

Internal documentation — org members only