ADR-0004: Appraisal & Feedback bounded context
Status
Accepted (engineering-ratified; reversible if a senior architect objects).
Context
ADR-0003 ratified ten bounded contexts and recorded, as open question #1 on the Bounded Contexts map, that the code contains a large cluster the ten-context list does not name: appraisal workflow, 360-degree feedback, MSF/MCR, WBA, and a set of compliance/program forms. The map deliberately left it provisional rather than guessing, and #8400 was raised to make the call before the #8253 (backend) and #8254 (frontend) reorganisations touch these files and scatter them inconsistently. The Yearly Appraisal build (#8178) is now authorised and needs a home.
This is an engineering boundary decision (ADR-0003 territory), not a Matt product call — the for-discussion label was removed for that reason. The issue ratifies a boundary only; no code moves in #8400.
Three options were on the table:
- A — promote to a dedicated "Appraisal & Feedback" context (an eleventh).
- B — split it: feedback/evidence (360, MSF, WBA, appraisal workflow) folds into CPD; the generic forms engine folds into Admin & Org as shared config.
- C — keep it provisional until a feature next touches it.
What the code actually shows
Findings from the current tree (api/backend-ppp, packages-shared/ppp, instances/ppp/src/modules):
- The appraisal cluster is internally cohesive and self-contained.
appraisalWorkflowService(state machine + evidence pack) depends only onappraisalAggregationService(its own context) plus the universally-allowed boundaries — Identity, Notifications, audit, DB, schema. It does not import CPD plan / PDP / SMART-goal / competency services. - The dependency runs one way.
appraisalAggregationServicereadscpdPlans,wba,wellness,ppp360, andreflectionto assemble the appraisal portfolio. Nothing in CPD, Wellness, or Logbook depends back on appraisal. The Yearly Appraisal "crossover" Matt describes in #8178 (the annual CPD-plan review rolling into the appraisal + PDP) is a composition flow across two contexts, not a code merge — appraisal consumes CPD evidence; it is not part of CPD. - It has its own ubiquitous language and spec. The
appraisals-wbaspec (capability "Professional Development & Evidence",status: built) frames it as a "single digital repository for career progression, accreditation, peer-to-peer learning, and performance tracking" and is slated to split intoappraisals.md,work-based-assessments.md, andyearly-appraisal.md. Terms (appraiser, evidence pack, 360, MSF, MCR, WBA) are appraisal-specific and shared by nothing else. - But the "forms engine" is genuinely cross-cutting — Option B was half right.
relatedFormService/relatedFormsis a polymorphic record-linking engine (inputRecordId→outputRecordId+ an open-stringtype). Itstypeconstants spancpdUserActivity,wba,reflection, andppp360, and it is consumed by CPD (activitiesService,cpdUserActivities), Logbook (logbookService), and MCR (mcrService) as well as appraisal.formPromptsService/formPromptsis the same shape of generic config. These are infrastructure, not appraisal-specific, and not Admin & Org either.
Decision
Adopt Option A with one refinement.
- Promote Appraisal & Feedback to the eleventh bounded context. It owns the appraisal workflow (
appraisalWorkflowService,appraisalAggregationService,appraisalReminderService), 360 (ppp360Service), and the appraisal-specific compliance/program forms (complianceFormService,programFormService); theappraisalWorkflow,appraisalReminders,ppp360,complianceForms,programFormsprocedures; theappraisalWorkflow,ppp360,ppp360reviews,ppp360reviewers,programForms,complianceFormSubmissionsschema; the WBA constants andforms/WBA*UI; and theAppraisalForm,MSF,WBA,PPP360Reviews,Reviewsfrontend modules. - Keep the generic record-linking / forms engine in
services/shared/—relatedFormService/relatedForms/relatedFormprocedure andformPromptsService/formPrompts/formPromptsprocedure. They are owned by no single context and invoked by any context that links a form/output record to a source record. This is the kept insight from Option B, without folding appraisal-specific forms into Admin & Org. - Cross-context evidence aggregation goes through service boundaries. As #8253 consolidates,
appraisalAggregationService's direct reads of CPD / Wellness / Logbook schema move behind those contexts' service calls.
MSFReport (open question #4) is not moved by this decision: it stays listed under Reports & Export with a cross-reference, pending the separate report-surface ownership call.
Consequences
Positive
- Appraisal files now have one obvious home; #8253 / #8254 can consolidate them under a single
appraisalcontext folder / module instead of scattering them across CPD and Admin & Org. - The Yearly Appraisal build (#8178) has a context to live in, and its CPD/PDP crossover is modelled correctly as a cross-context composition.
- The shared forms engine is named as shared infrastructure, so future features that need record-linking reuse it rather than duplicating it per context.
Negative / costs
- Eleven contexts instead of ten — a slightly larger map.
appraisalAggregationService's current direct cross-context schema reads are a known boundary smell to be paid down during #8253, not in this decision.- The
MSFReportownership question remains open (#4).
References
- This decision: #8400
- Parent epic: #8250 · map landed in #8251 (ADR-0003)
- Unblocks: #8253 (backend reorg), #8254 (frontend reorg)
- Related build: #8178 (Yearly Appraisal)
- Living reference: Bounded Contexts (open question #1, context 11)
- Spec:
appraisals-wba