Organisational Dashboard
Feature Overview
The Organisational Dashboard is the B2B-facing view of PPP. It serves Department, Hospital, Health Service and Governing Body Admins with high-fidelity, anonymised cohort insights drawn from the individual-doctor data the platform already captures, framed as OKRs (Objectives & Key Results) so feedback loops focus on meaningful progress.
The animating principle is: Protect Doctors. Elevate Organisations. Assist Organisations to Support Doctors. Individual-level data is aggregated into cohorts large enough to preserve privacy; the organisation sees patterns (CPD gaps, burnout signals, fatigue clusters) without ever seeing a specific Dr Smith's CPD shortfall.
Open Questions
| # | Question | Proposed answer / status | Ref |
|---|---|---|---|
| Q8 | How freely can the admin "chop up" cohort data themselves vs constrained views from us? | Engineering proposal: user-driven filters + anonymisation guard server-side; if combined filters fall under threshold, return aggregate-not-available. | Transcript 2026-05-20 §00:26:16 |
| Q9 | Feature uptake / adoption signal — Matt said admins should see "who do we need to promote certain features to because they're not uptaking certain things." Is this a cross-feature adoption metric (i.e. % of cohort who have logged ≥1 entry in each module), or is it implicit in the per-feature insight counts already specified? | Engineering proposal: implicit — if the count is 0 for a cohort-feature pair, that IS the low-uptake signal. No separate adoption metric needed unless Matt confirms otherwise. | Transcript 2026-05-20 §00:33:50 |
Closed Questions (8) — click to expand
| # | Question | Resolution | Ref |
|---|---|---|---|
| Q1 | Minimum cohort size that preserves privacy? | 5. Under-threshold cohorts show a user-facing message ("Not enough data to display — minimum 5 members required") rather than hiding silently. | Matt, 2026-05-20 |
| Q6 | Timezone for fatigue / shift-boundary metrics? | The hospital's timezone — look up the hospital the admin user is linked to and use its configured timezone for all shift-boundary calculations. | Matt, 2026-05-20 |
| Q2 | PGY groupings as a filter — include in v1 or defer? | Answered (transcript 2026-05-20 ~00:27:45): Include in v1. Matt specified "per PGY groupings or per department and specialty" as desired cohort filters. | Notion brief |
| Q3 | Which OKR templates ship in v1 vs v2? | Answered (transcript 2026-05-20 ~00:28:58): OKR framework confirmed for v1. Rob proposed OKRs as universal standard; Matt agreed. Specific OKR templates to be defined by engineering based on CPD/logbook/appraisal alignment metrics. | Transcript 2026-05-20 §00:28:58 |
| Q4 | AI summary toggle — per-section, per-user, or per-org policy? | Answered (transcript 2026-05-20 ~00:36:12): Per section, toggleable on/off by the user viewing the dashboard. Rob: "we can do it as a feature so we can turn it on and off." Matt agreed. | Transcript 2026-05-20 §00:36:12 / Notion |
| Q5 | Export audit — separate feed for PPP Staff, or just server-side logs? | Resolved 2026-06-03 — Built as a dedicated feed: getExportAuditForAdmin exposes export-audit rows to admins (#6735). code:api/backend-ppp/src/routers/procedures/auditTrail/index.ts. | #6735 |
| Q7 | Should Department Admin see a dashboard at all? Matt was wary about doctor-level insight at dept tier. | Resolved 2026-06-03 — Yes, dept-scoped roll-ups only (anonymised, no individual rows). The department_admin tier is built. code:api/backend-ppp/src/services/org-dashboard/cohort-anonymisation.service.ts. | Transcript 2026-05-20 §00:21:50 |
| Q10 | CPD engagement sub-metrics — a @issue-7326 BDD scenario asserts reminders_given and a 12-bucket monthly_entry_spread, but getCpdAlignment returned neither. Stay scoped to #7326, or is the scenario stale? | Resolved 2026-06-03 — Kept scoped to #7326 and built. getCpdAlignment now returns remindersGiven + a 12-bucket monthlyEntrySpread, both behind the k-anonymity guard. code:api/backend-ppp/src/routers/procedures/org-dashboard/cpd-alignment.procedure.ts. | #7326 |
Matt's Requirements (from Notion brief)
Source: Notion page — last edit 2026-05-20
Issue
- PPP collects sensitive user data. Under the overarching principle to protect doctors' personal information, data must be anonymised before it leaves the individual scope.
Purpose
- Provide high-level, high-fidelity anonymised grouped/cohort insights — accurate and real-time.
- Let the Organisation user chop up the data as they wish (filter / segment by Profile fields).
- Exportable reports (see
exportable-reports.md).
Grouping dimensions (authoritative)
Cohorts can be grouped / filtered by any combination of:
- Consultant vs Non-Consultant
- Per Job Role (the eight-value enum from Profile (Doctor))
- ?Per PGY groupings (flag — Matt marks with
?, needs confirmation) - Per Department / Speciality
- Per Hospital (for Hospital Admins)
- Per Health Service (for Health Service Admins)
- Per Organisation (for Governing Body Admins)
See Profile (Non Doctor) for the tier-based view-down model — admins can only query cohorts within their tier's scope.
Insight categories
Drawn from every individual-doctor feature that already captures data — to be framed as OKRs where possible:†
- CPD involvements — activity counts, category mix, compliance rates (anonymised). OKR template v1 (#7363): Objective "Our cohort is on track to be 100% CPD-compliant" → KR1 on-track ≥90%, KR2 prior-year compliance ≥95%, KR3 out-of-hospital ≥30% (all hospital-configurable).
- Logbook involvements — case volumes, role distribution, speciality coverage
- WBA involvements — assessments completed per assessor, competency score distributions
- Retrospective involvements — feedback counts, reflection counts, audit event linkage
- Appraisal involvements — MSF / MCR / 360 / Yearly completion rates
- Timesheet — time at work, fatigue incidents, missed lunch breaks
- Wellness — anonymised PPP Pulse / WHO-5 cohort signals
AI-generated summaries
- Each dashboard section carries a contextual AI summary that interprets the data and suggests actions, toggleable on/off by the user.†
- Summaries reference only the anonymised cohort data the admin already has visibility into; never leak under-threshold detail.
- Per-section toggle preference persists per user.
Regional inference
- High-level data must not obscure important specific details — the dashboard supports drill-down by hospital or department within the admin's scope.†
Acceptance Criteria
Core — anonymisation
- ✅ Every query enforces a minimum cohort size of 5 server-side; under-threshold queries return aggregate-not-available, not rows. (#7742) ‡
- ✅ When a section's cohort is below 5, the dashboard shows a user-facing message ("Not enough data to display — minimum 5 members required") rather than hiding silently or showing a blank.† (#7742) ‡
- ✅ No cohort-filter combination can triangulate a single doctor; combined filters falling below threshold return aggregate-not-available. (#7742) ‡
- ✅ Named doctor identifiers are never exposed in any dashboard response. (#7742) ‡
- ✅ Anonymisation is enforced in a single service layer, not repeated per-caller. (#7742) ‡
Scope enforcement (view-down)
Per Profile (Non Doctor):
- ✅ Hospital Admin queries scope to their own Hospital only; cross-hospital queries return 403. (#7742) ‡
- ✅ Health Service queries scope to hospitals within their Health Service only. (#7742) ‡
- ✅ Governing Body queries scope to hospitals within their Organisation only. (#7742) ‡
- ✅ Department Admin sees department-scoped roll-ups only (anonymised, no individual rows).‡
Grouping dimensions
- ⏳ Filters exposed for the seven dimensions in Matt's list (plus Country for multi-jurisdiction orgs if relevant).
- ✅ PGY groupings available as a cohort filter in v1.‡
Insight categories — minimum v1 set
- ✅ CPD compliance % per cohort (hours completed vs required, by Speciality). (#7328) ‡
- ✅ CPD engagement detail per cohort: number of reminders given and monthly activity-entry spread (so admins can see whether doctors rush entries at year-end vs distribute them evenly).† (#7326) ‡
- ✅ CPD-point source attribution per cohort: in-hospital vs out-of-hospital involvements.† (#7328) ‡
- ⏳ Logbook case volume per cohort, broken down by PGY level for non-consultants and by supervised vs primary-operating for consultants.†
- ⏳ WBA assessments per type (four types) per month per cohort; per PGY level for non-consultants; per assessor count for consultants.†
- ⏳ Retrospective engagement: feedback given vs received per cohort; reflections uploaded vs reviewed for consultants; uploaded-only for non-consultants; audit-event counts.†
- ⏳ Appraisal completion rate (MSF / MCR / 360 / Yearly per cohort).
- ⏳ Timesheet metrics per cohort: total time at work, fatigue shift hours, missed lunch breaks, overtime, digital recall — high-level only, never individual. All shift-boundary calculations use the timezone of the hospital the admin is linked to.†
- ⏳ Wellness per cohort: PPP Pulse readiness average + WHO-5 category breakdown + overall WHO-5 score.†
- ⏳ Each metric carries a last-refreshed timestamp.
Long-term lens — burnout early warning
- ⏳ Background analysis surface aggregates the above signals over time and exposes early-warning indicators for burnout per cohort.†
- ⏳ Early-warning output is itself cohort-anonymised; raised flags reference cohorts (e.g. "Department X / PGY3") never individuals.
OKR framework
- ✅ Each insight category supports one or more Objective templates (e.g. "100% CPD-compliant cohort, on track"), each with measurable Key Results that reinforce the objective.† (#7363) ‡
- ✅ CPD-alignment OKR v1 — Objective "Our cohort is on track to be 100% CPD-compliant" with three Key Results: KR1 on-track ≥90% (
headline.onTrackPct), KR2 prior-year compliance ≥95% (headline.compliancePct), KR3 out-of-hospital ≥30% (sourceMix.outOfHospitalPct). Targets are hospital-configurable; the card renders current-vs-target met/not-met per KR. (#7363) ‡ - ✅ OKR progress renders as a single headline number + trend per Objective. (#7328) ‡
- ✅ Admin can pin Objectives to the dashboard top; non-pinned Objectives still browsable. (#7328) ‡
- ✅ OKR thresholds (target Key Result values) are organisation-configurable. (#7328) ‡
AI summaries (per-section, toggleable)
- ✅ Each dashboard section renders a one-paragraph AI summary by default; user toggle hides per-section.† (#7328) ‡
- ✅ Summary respects the same anonymisation threshold — never references under-threshold groups. (#7328) ‡
- ✅ Summary includes an "actionable suggestions" sub-paragraph (≤3 bullets). (#7328) ‡
- ✅ Per-section toggle preference persists per user across sessions. (#7328) ‡
- ✅ Summary generation latency budget: ≤3s; on timeout, section renders without summary (no blocking). (#7328) ‡
Regional inference / drill-down
- ✅ Within an admin's scope, the dashboard supports drill-down filters (Hospital → Department) so high-level data doesn't obscure local detail.† (#7328) ‡
- ✅ Drill-down respects anonymisation — narrowing to a tiny department still hides under-threshold groups. (#7328) ‡
Real-time vs batch
- ⏳ Aggregates recompute on a cadence no slower than hourly.
- ⏳ Page load renders within 2s on typical (department-level) cohort sizes.
Export
- ⏳ Exportable reports in PDF and CSV (see
exportable-reports.mdfor shared layout). - ⏳ Export carries the same anonymisation threshold — would-be-leaky exports fail server-side with a user-facing message.
- ⏳ Export is audit-logged (actor, query, timestamp, row count).
Current Status
| Sub-feature | Status | Notes |
|---|---|---|
| Minimum-cohort-size anonymisation layer | 📋 Specified | Blocked on Q1 |
| Tier-based query scoping | 📋 Specified | Depends on profile-non-doctor.md |
| Grouping-dimension filters | ✅ Built | PGY + dimension filters supported; Q2 resolved (PGY in v1) — code:api/backend-ppp/src/services/org-dashboard/cohort-anonymisation.service.ts |
| Insight metric pipeline (materialised aggregates) | 🟡 Partial | CPD + WBA cohorts built (#6722/#6724); other modules deferred |
| OKR framework | ✅ Built | CPD/WBA headline+trend, pins, org-configurable thresholds (#6672/#6724) |
| AI summaries (per-section, toggleable) | ✅ Built | Per-section summary + persisted toggle + ≤3s budget (#6673) |
| Export (PDF + CSV) | ❌ Not started | See exportable-reports.md |
| Export audit | ✅ Built | getExportAuditForAdmin exposes the export-audit feed (#6735) — code:api/backend-ppp/src/routers/procedures/auditTrail/index.ts |
Open issues on label:feature:organisational-dashboard — no open issues. Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.
Downstream References
| Feature | Linkage |
|---|---|
| Profile (Non Doctor) | Admin tiers + view-down scoping |
| Profile (Doctor) | Grouping-dimension field definitions |
| Exportable Reports | Shared export layout + PPP branding |
| CPD | Source data for compliance metrics |
| Logbook | Source data for case-volume metrics |
| Appraisals / WBAs / Retrospective | Source data for involvement metrics |
| Timesheets | Source data for fatigue + missed-lunch metrics |
| HR Passport | Source data for Blue Tick compliance rate per cohort |
| Dashboard (Doctor-facing) | Sibling spec — individual view of similar data |
| MCP Provider | Exposes cohort metrics to external AI tools |
Change Log
| Date | Change | PR/Issue | Reason |
|---|---|---|---|
| 2026-06-22 | Added code-paths: front-matter (OrganisationalInsights + HospitalAdmin/Insights modules + org-dashboard/** procedures and services). | #9068, #9056 | SGD C6 drift — the built Organisational Dashboard spec had no code-traceability metadata. |
| 2026-06-17 | Surface the two CPD engagement sub-metrics (added API-only in #7326/PR #8213) on the org-dashboard Insights UI. The CPD alignment OKR card now renders a visible reminders-given count and a 12-bar Jan-Dec monthly entry-spread mini-chart (CpdEngagementSubMetrics), so admins can see at a glance whether doctors rush CPD entries at year-end vs distribute them evenly. Both render only when the cohort clears the k-anonymity threshold — below it the existing anonymisation message shows and neither metric appears. The mini-chart carries a role=img accessible label enumerating all 12 month buckets; the count carries an aria-label. Un-wip the parked @issue-7326 journey scenario (now @regression @issue-8218) and harden its Then-steps to assert the real rendered shape (12 month buckets in the chart label, a non-negative integer reminders count) instead of the prior soft presence placeholders. | #8218, #7326 | #8218 — PR #8213 (#7326) shipped the metrics API-only; the journey was not browser-testable until this UI existed. This completes the user-facing half of the Insight-categories AC. Pure frontend wiring (no schema/API change); MUI semantic palette tokens only (primary.main / action.disabledBackground), no hardcoded colours. |
| 2026-06-03 | Add the two CPD engagement sub-metrics to the org-dashboard CPD insight API (getCpdAlignment), both behind the existing k-anonymity guard. remindersGiven counts CPD reminder notifications sent to the cohort this plan year using the canonical CPD_REMINDER_TYPES set (the four reminder Container Apps Jobs); monthlyEntrySpread is a 12-element Jan-Dec array of CPD activity entries the cohort logged per month this year (excludes archived), so admins can spot year-end rushing vs an even spread. Both scope to the exact user-id set the guard cleared so membership stays identical to the rest of the OKR; no schema migration (sourced live from notifications + cpd_user_activities). Flip the Insight-categories AC to ✅, wire the two outstanding @issue-7326 BDD Then-steps, and add integration coverage (12-bucket shape, non-negative integers, below-threshold exposes neither field). | #8213, #7326 | #7328 audit surfaced drift (spec Q10) — an @issue-7326 BDD scenario asserted reminders_given + a 12-bucket monthly_entry_spread but getCpdAlignment returned neither. /deep-dive confirmed the feature was real and deferred here, not stale. API-only for v1 (frontend surfacing is a follow-up). Fields are camelCase to match the rest of the result; reminders defined as the current plan year to match the cohort. |
| 2026-06-03 | Resolve Q5/Q7 to Closed Questions and flip the PGY-filter, export-audit (#6735) and department-admin-tier ACs to delivered. | #8166 | SGD governance sweep — transcript-grounded audit found these questions already answered; reconciled the spec to shipped reality and moved them out of Open Questions. |
| 2026-06-01 | Wire the canonical CPD-alignment OKR v1 onto the Organisational Dashboard. Add three hospital-configurable Key Result targets (cpd_ontrack_target_pct=90, cpd_prioryear_compliance_target_pct=95, cpd_out_of_hospital_min_pct=30) to okr-thresholds; getCpdAlignment now returns the objective "Our cohort is on track to be 100% CPD-compliant" plus a keyResults[3] array (on-track / prior-year-compliance / out-of-hospital), each currentPct vs targetPct with a met flag, mapped from fields it already computed (no new query). CpdAlignmentSection renders the 3 KR rows (current %, target chip, met/not-met indicator); below the cohort threshold the existing anonymisation guard's aggregate-not-available message renders and no KRs are shown. Flip the OKR-framework AC to ✅ and add the OKR template to Insight categories. Two @smoke @issue-7363 BDD scenarios cover the qualifying-cohort and below-threshold paths. | #7924, #7363 | #7363 groomed the vague "define OKRs" chore into a thin-wiring task once it was confirmed the OKR infrastructure (org_dashboard_okr_thresholds, okr-pins, getCpdAlignment) already existed and cpd-alignment.procedure.ts already named the intended OKR (#6724). Targets 90/95/30 are Rob's v1 defaults — sensible to revisit with real cohort data, not yet Matt-confirmed. The "spread through the year" objective (monthly_entry_spread + reminders_given) stays deferred to #7326 per spec Q10. |
| 2026-06-01 | Finish the deterministic latency-budget BDD coverage for the AI section summary. The "AI summary that exceeds the latency budget renders the section without a summary" scenario is un-@wip'd and now stubs the timeout path batch-aware — fetching the real httpBatchLink response and rewriting only the generateSectionSummary entry by its index in the comma-joined procedure path, so the sibling getSectionSummaryPrefs query survives and the summary toggle stays ON. The card then renders the { available:false } "Summary unavailable — please try again." message with no suggestion list, and the OKR section still renders without blocking. | #7865, #7328 | Follow-up from the Copilot review on #7863. The summary and prefs queries batch into one request, so the previous single-entry stub skipped batched requests and the scenario could not pass for the right reason (parked @wip @known-issue-7865). Rewriting only the target batch index preserves siblings and exercises the real timeout fallback. Scenario stays @requires-backend (needs a seeded ≥5-doctor cohort so the section renders available and the card mounts) and is verified in the backend-enabled lane. |
| 2026-06-01 | Flip 12 verified ACs from ⏳ to ✅ with traceable code citations — CPD compliance % + source mix, OKR headline/trend, OKR pins, org-configurable thresholds, per-section AI summaries (default render, anonymisation threshold, ≤3 suggestions, persisted toggle, ≤3s latency budget), and Hospital→Department drill-down (with anonymisation). Add two @regression BDD scenarios (#7328) for the AI summary suggestions cap and latency-budget fallback. | #7863, #7328 | The #7328 audit confirmed the org-dashboard OKR, AI-summary and drill-down code is implemented and BDD-covered but the spec markers were stale. Docs-only reconciliation. Raised Q10 for the #7326 CPD engagement sub-metrics drift (reminders_given / monthly_entry_spread asserted by a BDD scenario but not yet returned by getCpdAlignment) — that AC stays ⏳. WBA per-month/per-PGY breakdown and the seven-dimension filter set also remain ⏳. |
| 2026-05-27 | Flip 8 verified anonymisation + scope-enforcement ACs (minimum cohort size of 5, below-threshold user-facing message, no-triangulation guard, named-identifier guard, single-service-layer SSOT, Hospital Admin 403, Health Service scope, Governing Body scope) from ⏳ to ✅ with traceable code citations into cohort-anonymisation.service.ts and wellness-privacy.guard.ts. | #7752, #7742 | The org-dashboard anonymisation and scope code is fully implemented at a single service layer and BDD-covered, but the spec markers were stale (the #7328 audit flagged 0 ✅ ACs). Docs-only reconciliation; Department Admin scope stays ⏳ pending Q7 (#7360). |
| 2026-05-22 | SGD audit 2026-05-20: add CPD sub-metrics AC (reminders-given + monthly entry spread) and Open Question Q9 (feature uptake signal) | #7326 | Transcript 2026-05-20 §00:28:58 — Matt explicitly stated reminders-given count and monthly entry spread as desired CPD cohort insight fields. Feature uptake signal (§00:33:50) treated as Open Question pending Matt confirmation. |
| 2026-05-20 | Add OKR framework, toggleable per-section AI summaries, regional inference drill-down; align tier scoping with the 5-level hierarchy. | #0 | Matt's 2026-05-20 Dev Session: OKRs keep feedback loops focused; AI summaries surface analysis without forcing UI dwell; drill-down prevents high-level data from hiding local detail. |
| 2026-05-19 | Transcript audit 2026-05-19 — §26 classified C (context); notion-last-synced updated. | #~ | §26 of the 2026-05-19 Dev Session transcript records a prioritisation decision: the team agreed to mock up the Organisational Dashboard to demonstrate hospital administrative staff capabilities to funders ahead of the 28 May 2026 investor meeting. This is project/demo context, not a new product AC — no spec ACs changed. notion-last-synced updated to reflect the audit date. |
| 2026-04-21 | Spec created from Matt's 17 Apr 2026 Notion brief | this PR | Wave 5 — new B2B-facing feature. Consolidates prior CMO view concept (#3632) + Profile (Non Doctor) tiered scoping + cross-feature insight aggregation |