Skip to content
View in Notion

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.md together define every user type on the platform.

Open Questions ​

#QuestionProposed answer / statusRef
Q3Should 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
#QuestionResolutionRef
Q-AHow 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-BSuper Admin enterprise inclusion?Unlimited seats, included in Enterprise agreement.Transcript 2026-05-20 §00:12:05
Q-CActivation 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-DDepartment 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
Q1Activation 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
Q2UK 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
Q4Are 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
Q5Bulk 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.

  1. Department Admin — Hospital Admin scoped to one department (one secretary may cover several departments in small hospitals).†
  2. Hospital Admin — single hospital.
  3. Health Service — a group of hospitals (Queensland Health: 16 Health Services; UK equivalent is Trust).†
  4. Governing Body — across multiple Hospital groups within one organisation (e.g. Queensland Health overall).†
  5. 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.
  • 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.
  • 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.

  1. PPP Staff (or an existing higher-tier admin within scope) creates an invite carrying persona type, scope ids, and recipient email.
  2. Recipient receives a single-use magic-link email (HMAC-SHA256, 7-day TTL — same primitive as the timesheet approver token in timesheets.md).
  3. Clicking verifies the email and provisions the persona record in pending state.
  4. 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_admin rows by tier into the four new enum values.
  • ✅ Data model carries a tier_level integer (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 finance sub-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 doctorSeatsUsed count (active doctor memberships) against an explicit "Unlimited" allowance (seatLimit is 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 — userPersona enum 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_ids to issue bulk invitations.†
  • ⏳ Accepted persona values in the CSV match the userPersona enum 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_ids referencing 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-featureStatusNotes
Five-persona enum data model⚠️ Partial driftCode currently has 3 personas + tier; migration epic raised
Department Admin activation❌ Not startedBlocked on migration
View-down tiering📋 SpecifiedOrganisational Dashboard will consume
PPP Staff finance sub-role⚠️ PartialStripe in place; formal sub-role gate missing
Enterprise SSO❌ Not startedNew requirement (transcript 2026-05-20)
Bulk enrolment❌ Not startedNew requirement (transcript 2026-05-20)
Export anonymisation❌ Not startedDepends 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 ​
FeaturePersona field usedConsequence
AttendanceDepartment Admin (scope)Who can create events + invite filter
TimesheetDepartment Admin (scope)Forwarding destination for approved timesheets
Organisational DashboardAll four org admin tiersQuery scope + anonymisation enforcement
Exportable ReportsAll four org admin tiers + PPP StaffCohort report scoping
BillingPPP Staff (finance sub-role)Gate for Stripe / billing operations
Admin governancePPP StaffAccount CRUD and impersonation
Change Log ​
DateChangePR/IssueReason
2026-06-01Add 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-01Added 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.#7877Deep-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-20Remove 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-20Migrate to 5-level hierarchy (Department / Hospital / Health Service / Governing Body Admin + PPP Staff); unlimited admin seats; bulk enrolment; Enterprise SSO.#0Matt'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-20Expand Bulk Enrolment ACs (9 criteria) + create profile-non-doctor.feature BDD file with 10 @wip scenarios (blocked on #6669 RBAC migration).#6670Spec 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-05Engineering-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.#5565Resolves 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-21Spec 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 permissionsthis PRWave 1 foundation — Attendance, Timesheet, and Organisational Dashboard specs cite these personas

Internal documentation — org members only