Profile (Non Doctor)
Feature Overview
Non-doctor profiles cover the five platform tiers who are not clinicians: Department Admin, Hospital Admin, Health Service Admin, Governing Body Admin, and PPP Staff. Each tier has distinct scope, view-down visibility, and seat economics. This spec supersedes admin.md.
📌 This spec plus
profile-doctor.mdtogether define every user type on the platform.
Open Questions
| # | Question | Proposed answer / status | Ref |
|---|---|---|---|
| Q3 | Should Department Admin have a dashboard at all? Matt is wary about doctor-level insight at the dept tier. | Engineering proposal: yes, but no individual-doctor metrics — only roll-ups, with the same anonymisation threshold as higher tiers. | Transcript 2026-05-20 §00:21:50 |
Closed Questions (8) — click to expand
| # | Question | Resolution | Ref |
|---|---|---|---|
| Q-A | How many Hospital Admin seats per hospital? Included in Enterprise agreement? | Unlimited seats for all org admin tiers as a goodwill offering. Platform charges for doctor seats only. | Transcript 2026-05-20 §00:12:05 |
| Q-B | Super Admin enterprise inclusion? | Unlimited seats, included in Enterprise agreement. | Transcript 2026-05-20 §00:12:05 |
| Q-C | Activation mechanism for Hospital Admin and Super Admin — token, link, or code? | Invite + single-use magic-link (HMAC-SHA256, 7-day TTL). Self-service sign-up disabled for non-doctor personas. | 5 May engineering decision |
| Q-D | Department fidelity on sign-up page? | Captured on the invite payload, not the public sign-up page (which is disabled for non-doctor personas). | 5 May engineering decision |
| Q1 | Activation across all four org tiers — confirm invite + magic-link still applies post-5-level rename. | Answered (transcript 2026-05-20 ~00:18:02): 4-tier hierarchy confirmed as: Department Admin, Hospital Admin, Health Service Admin, Governing Body Admin. PPP Staff = 5th level (separate). Invite + magic-link pattern applies. | Transcript 2026-05-20 §sign-up Notion |
| Q2 | UK has one additional tier (Trust / Region between Health Service and Governing Body) — wire it in v1 or v2? | Answered (transcript 2026-05-20 ~00:19:08): One extra UK tier confirmed (Trust/Region between Health Service and Governing Body). Matt: "there'll be one more tier in the UK." Rob: "Let's build it for Australia now." UK tier deferred to UK launch phase — architecture must be modular to accommodate it. | Transcript 2026-05-20 §00:19:08 / §00:20:24 |
| Q4 | Are Health Service and Governing Body Admin seats capped (not unlimited)? | All five admin tiers: unlimited seats, free. Matt confirmed 2026-05-20: admin seats are a goodwill offering; only doctor seats are metered. | Transcript 2026-05-20 §00:14:49 / confirmed 2026-05-20 |
| Q5 | Bulk enrolment authorisation — who may issue invites in bulk (PPP Staff only, or also Governing Body)? | Answered (transcript 2026-05-20 ~00:22:57): Bulk enrolment via CSV email import + role assignment. Rob: "you just want a whole bunch of email addresses to import... select the roles for them in bulk and send it out." Governing Body and Hospital Admin can issue bulk invites. | Transcript 2026-05-20 §00:22:57 |
Matt's Requirements (from Notion brief)
Source: Notion page — last edit 2026-05-20
Five-level hierarchy
Naming was negotiated live in the transcript (§00:18:02 → §00:20:24). Matt initially proposed "department admin, hospital admin, hospital super admin, governing body admin"; Rob pushed back on "hospital super admin"; settled order is below. Display names follow Matt's voice (no "Admin" suffix on Health Service or Governing Body); enum values keep _admin for code consistency.
- Department Admin — Hospital Admin scoped to one department (one secretary may cover several departments in small hospitals).†
- Hospital Admin — single hospital.
- Health Service — a group of hospitals (Queensland Health: 16 Health Services; UK equivalent is Trust).†
- Governing Body — across multiple Hospital groups within one organisation (e.g. Queensland Health overall).†
- PPP Staff (Super Admin) — platform operators.
Modularity requirement (UK lens): the UK has one additional tier — Trust sits inside a Region. Build the data model so an extra tier can be inserted without enum migration.†
Persona 1 — Department Admin
- Seat model: unlimited per department, included in Enterprise agreement.†
- Multi-department coverage: one Department Admin may be assigned to several departments in a small hospital; the UI must surface a department-selector dropdown when more than one is assigned.†
- Functions:
- Set meetings that trigger CPD (see
attendance.md). - Officiate internal CPD activities and issue certification (MDT / M&M / Audit).
- Receive timesheets from Timesheet Approver and upload them into the hospital's internal system.
- Set meetings that trigger CPD (see
- Scope fields: Hospital, Department.
Personas 2–4 — Hospital Admin / Health Service / Governing Body
- Seat model: unlimited for all three tiers, included in Enterprise agreement. Admin seats are a goodwill offering; only doctor seats are metered.†
- Tier model — strict view-down:
- Governing Body Admin views all Health Services and Hospitals within its organisation.
- Health Service Admin views all Hospitals within its Health Service; cannot see sibling Health Services.
- Hospital Admin views its own Hospital; cannot see sibling Hospitals.
- No upward visibility. No tier sees data outside its scope.
- Functions:
- View Organisational Insights (see
organisational-dashboard.md). - Generate exportable cohort reports — anonymised, non-sensitive doctor information only.
- View Organisational Insights (see
- Scope fields: Organisation, Health Service, Hospital (only the level the persona occupies and below).
Persona 5 — PPP Staff
- Functions: administrative function of the platform; access and approvals (grant/revoke/review); account editing and assistance; billing and accounting.
Sign-up / activation
Activation is invite + email magic-link, not self-service sign-up.
- PPP Staff (or an existing higher-tier admin within scope) creates an invite carrying persona type, scope ids, and recipient email.
- Recipient receives a single-use magic-link email (HMAC-SHA256, 7-day TTL — same primitive as the timesheet approver token in
timesheets.md). - Clicking verifies the email and provisions the persona record in
pendingstate. - PPP Staff approve to flip pending → active.
Self-declared admins are blocked (mirrors the consultant-approver guard added in #4822 / #4840).
Enterprise SSO
- Organisational admins use their enterprise/professional admin account — sign-in must verify the bound enterprise SSO (M365 / Okta / SAML).†
- Magic-link invite remains for first-time linkage; subsequent logins use the bound IdP.
Bulk enrolment
- Authorised tiers can bulk-invite 30–150 admins by importing email addresses + assigning roles in one operation — onboarding for "really busy" admins must not require manual form-fill.†
Acceptance Criteria
Core — five-level persona data model
- ⏳ Persona enum:
department_admin,hospital_admin,health_service_admin,governing_body_admin,ppp_staff.† - ⏳ Persona type immutable post-activation; changes require PPP Staff action with audit entry.
- ⏳ Scope fields (Hospital / Department / HealthService / Organisation) validate against Doctor Profile reference tables.
- ⏳ Migration renames existing
hospital_super_adminrows by tier into the four new enum values. - ✅ Data model carries a
tier_levelinteger (1–5) so an additional tier can be inserted (e.g. UK Trust/Region) without enum migration.†‡
Department Admin
- ⏳ Record carries one Hospital + one or more Departments.†
- ⏳ Cross-hospital department assignment rejected (departments must belong to the same Hospital).
- ⏳ When more than one department is assigned, UI surfaces a department-selector dropdown to switch context.†
- ⏳ Can create Attendance events scoped to their Hospital + selected Department.
- ⏳ Can issue certification for officiated internal CPD meetings (MDT / M&M / Audit).
- ⏳ Can forward an approved timesheet to the hospital's payroll system.
- ⏳ Cannot view data outside their Hospital + assigned Departments scope.
Hospital Admin
- ⏳ Record carries one Hospital id.
- ⏳ Sees all Departments within its Hospital; cannot query sibling Hospitals.
- ⏳ Can generate exportable cohort reports scoped to its Hospital.
Health Service Admin
- ⏳ Record carries one Health Service id.
- ⏳ Sees all Hospitals within its Health Service; cannot query sibling Health Services.
- ⏳ Can generate exportable cohort reports scoped to its Health Service.
Governing Body Admin
- ⏳ Record carries one Organisation id.
- ⏳ Sees all Health Services and Hospitals within its Organisation.
- ⏳ Can generate exportable cohort reports scoped to its Organisation.
PPP Staff
- ⏳ Scope of
platform— full access. - ⏳ Can impersonate / switch-to a user for support (audit-logged).
- ⏳ Billing and accounting functions gated behind a
financesub-role.
Seat economics
- ⏳ All five admin persona tiers: unlimited seats, included in Enterprise agreement.†
- ⏳ Platform billing meters doctor seats only; admin seats do not increment the count.
- ⏳ Admin tiers provision unlimited doctor seats: a hospital admin can attach/approve any number of doctors with no seat cap and no blocking error.†
- ⏳ Doctor seat usage is metered for reporting only: the executive dashboard surfaces a
doctorSeatsUsedcount (active doctor memberships) against an explicit "Unlimited" allowance (seatLimitis always null) — visibility, never enforcement.† ‡
Activation / approval
- ⏳ Invite-only: higher-tier admin issues invite carrying persona type + scope ids.
- ⏳ Recipient confirms via single-use magic-link (HMAC-SHA256, 7-day TTL).
- ⏳ PPP Staff approve to flip pending → active.
- ⏳ Self-service sign-up disabled for the four organisational admin personas.
- ⏳ Magic-link follows the timesheet-approver template style; HMAC primitive (no shared secret).
Enterprise SSO
- ⏳ Organisational personas may bind their account to an enterprise SSO provider after activation.†
- ⏳ Once SSO is bound, password login is disabled for that account (security policy).
- ⏳ SSO binding metadata is persona-scoped (different tiers may use different IdPs).
Bulk enrolment
Blocked by: #6669 —
userPersonaenum must land before this can be implemented. Q5 (who may bulk-invite) is open; engineering proposes PPP Staff + Governing Body Admin.
- ⏳ PPP Staff and Governing Body Admin may upload a CSV (or XLSX) of rows with columns
email,persona,scope_idsto issue bulk invitations.† - ⏳ Accepted
personavalues in the CSV match theuserPersonaenum exactly:department_admin,hospital_admin,health_service_admin,governing_body_admin,ppp_staff. - ⏳ Per-row validation: invalid email format → row error; unrecognised persona value → row error;
scope_idsreferencing a non-existent Hospital / HHS / Organisation → row error. Valid rows are still processed when sibling rows fail. - ⏳ After upload, the UI shows a results summary: total rows, success count, failure count, and a per-row error list (email + reason) for failed rows.
- ⏳ Maximum 200 rows per upload; files exceeding this limit are rejected before processing begins with a clear count error.
- ⏳ Duplicate detection: a row whose email already has an active or pending invite for the same persona + scope is skipped (not an error); skip count appears in the results summary.
- ⏳ Each successfully processed row triggers the same single-invite magic-link email flow (7-day TTL, HMAC-SHA256 signed) — no separate bulk email template required.
- ⏳ A single audit log entry is written per bulk upload: actor, timestamp, total rows submitted, success count, failure count. Action:
bulk_invite_issued, entity type:user. - ⏳ Hospital Admin and Health Service Admin personas do not see the bulk upload control — restricted to PPP Staff and Governing Body Admin only.
Current Status
| Sub-feature | Status | Notes |
|---|---|---|
| Five-persona enum data model | ⚠️ Partial drift | Code currently has 3 personas + tier; migration epic raised |
| Department Admin activation | ❌ Not started | Blocked on migration |
| View-down tiering | 📋 Specified | Organisational Dashboard will consume |
| PPP Staff finance sub-role | ⚠️ Partial | Stripe in place; formal sub-role gate missing |
| Enterprise SSO | ❌ Not started | New requirement (transcript 2026-05-20) |
| Bulk enrolment | ❌ Not started | New requirement (transcript 2026-05-20) |
| Export anonymisation | ❌ Not started | Depends on organisational-dashboard.md |
Open issues on label:feature:profile-non-doctor — issue data unavailable at build time.Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.
Downstream References
| Feature | Persona field used | Consequence |
|---|---|---|
| Attendance | Department Admin (scope) | Who can create events + invite filter |
| Timesheet | Department Admin (scope) | Forwarding destination for approved timesheets |
| Organisational Dashboard | All four org admin tiers | Query scope + anonymisation enforcement |
| Exportable Reports | All four org admin tiers + PPP Staff | Cohort report scoping |
| Billing | PPP Staff (finance sub-role) | Gate for Stripe / billing operations |
| Admin governance | PPP Staff | Account CRUD and impersonation |
Change Log
| Date | Change | PR/Issue | Reason |
|---|---|---|---|
| 2026-06-01 | Add a tier_level integer (1–5) hierarchy dimension alongside the fixed persona enum; scope expansion now keys off the integer level, so a new region's tier can be inserted without an enum migration. Flips the tier_level AC to done. | #7983, #'7876' | Re-parentable hierarchy was the one genuinely-unbuilt piece of the "modular for other regions" requirement (spun out of #7360). Behaviour-preserving — every existing persona maps to its documented level with no change; readies the deferred UK Trust/Region tier. |
| 2026-06-01 | Added seat-usage metering for admin tiers — executive dashboard now surfaces a read-only doctorSeatsUsed count against an explicit "Unlimited" allowance; admin tiers still provision unlimited doctor seats with no cap. | #7877 | Deep-dive decision (2026-06-01) — capture the unlimited-seats goodwill promise as an explicit testable AC and add seat-usage visibility for reporting, NOT a hard cap, so a future doctor-seat billing change knows the unlimited behaviour was intentional. |
| 2026-05-20 | Remove stale "Hospital Super Admin" UI copy; rename to "Org Admin" pending 5-level enum migration (#6679). Mark admin.md as superseded by profile-non-doctor.md. | #6708, #'6678' | Drift fix — the old two-tier "Hospital Admin / Hospital Super Admin" terminology was replaced by the 5-level hierarchy in SGD audit 2026-05-20. UI copy updated ahead of schema migration to avoid confusing operators. |
| 2026-05-20 | Migrate to 5-level hierarchy (Department / Hospital / Health Service / Governing Body Admin + PPP Staff); unlimited admin seats; bulk enrolment; Enterprise SSO. | #0 | Matt's 2026-05-20 Dev Session ratified the new hierarchy and seat economics; existing spec used a 3-persona + tier model that diverges from the agreed naming. |
| 2026-05-20 | Expand Bulk Enrolment ACs (9 criteria) + create profile-non-doctor.feature BDD file with 10 @wip scenarios (blocked on #6669 RBAC migration). | #6670 | Spec section referenced by #6670 was missing; BDD file listed in frontmatter but not yet created. Option A from deep-dive — spec and scenarios now in place for the implementation pass once #6669 Parts 1-3 land. |
| 2026-05-05 | Engineering-led activation flow — invite + magic-link (HMAC-SHA256, 7-day TTL) reusing the timesheet-approver primitive. Self-service sign-up disabled for non-doctor personas. Department fidelity captured at invite time, not at sign-up. | #5565 | Resolves Q3 + Q4 in #5565 with a default that mirrors the consultant-approver guard (#4822/#4840) and the timesheet token primitive. Seat economics (Q1, Q2) remain Matt-blocked but a default proposal is on the table for him to accept or correct. |
| 2026-04-21 | Spec created from Matt's 17 Apr 2026 Notion brief. Supersedes admin.md — old spec collapsed governance into a single feature; Matt now splits into three personas (Hospital Admin, Super Admin, PPP Staff) with distinct scopes and permissions | this PR | Wave 1 foundation — Attendance, Timesheet, and Organisational Dashboard specs cite these personas |