Staff App Mode – Technical Specification

1. Module Purpose & Scope (Authoritative)

Staff App Mode is the secure, practice-owned mobile experience for staff coordination, communication, and everyday requests within Primoro. It replaces informal tools such as WhatsApp, personal SMS, and shared drives, keeping practice data out of personal messaging spaces and giving staff one trusted place for updates, rotas, tasks, and requests. It enforces rota-aware quiet hours to protect work–life boundaries, and ensures that all staff communication and actions are auditable and revocable.

It governs:

• Providing a secure, staff-only authenticated mobile interface, distinct from the patient-facing app surface
• Surfacing role-relevant information, tasks, requests, documents, and communication primitives sourced from system-of-record modules
• Enforcing quiet hours, audit logging, and access revocation for all staff interactions on personal devices

It explicitly does not:

• Own conversation routing or message delivery logic — that concern is owned by Communication Hub
• Execute or own tasks and callbacks — that concern is owned by Task Manager
• Own rota scheduling, shift management, or coverage decisions — that concern is owned by Rota Manager
• Own appointment booking or scheduling — that concern is owned by Appointment Manager
• Author clinical records — that concern is owned by the PMS
• Own payroll, HR records, or employment contracts

Staff App Mode is a surface layer, not a system of record.

2. Ownership & Responsibilities

2.1 Staff App Mode IS Responsible For

• Providing and securing the staff-only mobile interface, including mode separation from the patient surface
• Enforcing authentication, session management, biometric re-authentication, and immediate access revocation
• Surfacing role-scoped views of tasks, rotas, messages, documents, requests, and announcements — consuming from system-of-record modules
• Enforcing rota-aware quiet hours for notification delivery
• Enabling structured staff requests (holiday, sickness, shift swaps, errands, expenses, ideas, anonymous feedback) as tracked, auditable submissions
• Supporting staff-assisted form completion and recording attribution in the audit trail
• Surfacing document acknowledgement prompts and recording confirmations back to Document Hub
• Encrypting all practice data stored locally on personal devices at rest
• Maintaining a complete, immutable audit trail of all staff access, actions, and submissions within this surface

2.2 Staff App Mode IS NOT Responsible For

• Conversation routing and delivery logic — owned by Communication Hub
• Task creation, ownership, or resolution — owned by Task Manager
• Rota authoring, scheduling, or adjustment — owned by Rota Manager
• Appointment booking — owned by Appointment Manager
• Form ownership, routing, or storage — owned by Digital Forms
• Document authorship and versioning — owned by Document Hub
• Dashboard card definitions and alert signal logic — owned by Smart Dashboards
• Identity management and RBAC rule authoring — owned by Access Manager
• Payroll, HR records, or employment contracts — out of platform scope at this tier

3. Core Objects (Normative)

3.1 StaffSession (Canonical Artefact)

A StaffSession is a governed digital artefact representing a single authenticated staff-mode session on a specific device.

Minimum required fields:

• UserId
• DeviceId
• AuthMethod
• LoginTimestamp
• LastActiveTimestamp
• LogoutTimestamp
• AuditTrail (immutable — records mode activation, lock, unlock, and logout events)

3.2 StaffSession State Machine (Authoritative)

States:

• Active — staff authenticated and session in use
• Locked — session exists but requires PIN or biometric re-authentication after inactivity
• Terminated — staff has logged out or access has been revoked server-side

Rules:

• A session moves from Active to Locked automatically after a configurable inactivity timeout
• A session moves from Locked back to Active only on successful PIN or biometric re-authentication
• A session moves to Terminated on explicit logout or on server-side access revocation; Terminated sessions cannot be resumed
• Server-side role or access changes apply immediately to the active session without requiring re-login
• All state transitions are time-stamped and recorded in the immutable audit trail

3.3 StaffRequest (Canonical Artefact)

A StaffRequest is a governed digital artefact representing a formalised staff submission requiring a practice response.

Minimum required fields:

• RequestId
• RequestType (Leave | Sickness | Expense | Swap | Errand | Idea | Anonymous)
• SubmittedBy
• Status
• CreatedAt
• LastUpdatedAt
• AuditLog (immutable)

3.4 StaffRequest State Machine (Authoritative)

States:

• Submitted — request received and awaiting review
• Under Review — request acknowledged and being actioned
• Resolved — request concluded
• Cancelled — request withdrawn by submitter or voided by manager

Rules:

• A request moves from Submitted to Under Review when acknowledged by a manager
• A request moves from Under Review to Resolved on completion of the response workflow
• A Submitted request may be Cancelled by the submitter or by a manager
• All state transitions are time-stamped, attributed to an actor, and recorded in the immutable AuditLog
• Anonymous requests (RequestType = Anonymous) MUST NOT surface the submitter's identity to any reviewing actor

3.5 Notification (Canonical Artefact)

A Notification is a governed artefact representing a single delivery attempt of an update or alert to a staff member.

Minimum required fields:

• NotificationId
• SourceModule
• Urgency (Normal | Urgent)
• Delivered (Delivered | Suppressed)
• Timestamp
• RecipientUserId

4. Authentication & Access

4.1 Hidden Staff Login (Authoritative)

Staff App Mode is accessed via a hidden activation gesture that is not discoverable by patient users. Staff authenticate via:

• SSO with Microsoft or Google (Azure AD) where configured
• MFA where configured by the practice
• Local Primoro login for locums and staff without organisational SSO accounts

Authentication uses the same identity system as the web portal, governed by Access Manager. Locums are provisioned as named users within Access Manager and authenticate via local Primoro credentials scoped to their scheduled shifts; they do not require organisational SSO. Patients cannot discover or access staff mode. Staff and patient contexts are mutually exclusive and cannot coexist within a single session.

Hidden Activation Gesture (Security Boundary)

The hidden activation gesture is a non-negotiable security boundary. It MUST be evaluated and passed before any staff authentication screen is presented to the user; the authentication surface itself MUST NOT be reachable without it. This ensures that a patient using the device cannot stumble upon the staff login screen through normal navigation. The gesture is platform-enforced and is not surfaced in any public-facing UI affordance, help text, or onboarding flow accessible to patient users. The specific gesture implementation is defined at the platform level and is treated as a reserved security detail; it MUST NOT be documented in any patient-facing material.

The module MUST:

• Prevent any patient user from discovering or activating staff mode
• Evaluate and pass the hidden activation gesture before presenting any staff authentication screen
• Fully clear staff access on logout
• Apply server-side access changes immediately to active sessions

The module MUST NOT:

• Allow anonymous or shared staff sessions
• Allow staff and patient modes to coexist

4.2 Session Behaviour (Authoritative)

• Staff sessions persist during the working day
• The app auto-locks after a configurable inactivity period
• Re-authentication via PIN or biometrics is required to unlock a locked session
• Server-side role or access changes apply immediately without requiring re-login

5. Staff Capabilities

5.1 Communication & Updates

Staff App Mode surfaces the following Communication Hub primitives:

• Chats — direct and group secure messaging, replacing WhatsApp and personal SMS
• Channels — team and role-based discussion threads
• Announcements — practice-wide broadcast messages
• Praise — peer recognition visible within the app
• Acknowledgements — confirmations that a message or update has been seen
• Structured Requests — formalised request threads with defined response workflows

All message history is fully auditable. Primitives not listed above are not surfaced in Staff App Mode. Communication Hub owns routing and delivery logic; Staff App Mode owns only the surface rendering.

Mobile Surface Detail

Staff App Mode renders Communication Hub's Chat and Channel primitives as the primary in-app messaging experience on mobile, replacing informal direct messages and group chats held on personal messaging applications. Each Chat or Channel thread is rendered inline within the app; staff can compose, send, and read messages without leaving the Staff App Mode surface. Push notifications for incoming messages are subject to quiet hours enforcement (see §6): Normal-urgency message notifications are suppressed off-shift, whilst Urgent-urgency notifications are delivered regardless of rota state. Notification routing decisions remain the responsibility of Communication Hub; Staff App Mode receives the resulting delivery instruction and renders or suppresses accordingly.

5.2 Tasks, Callbacks & Actions

Staff App Mode surfaces task queues sourced from Task Manager. Staff may:

• View personal and role-based task queues
• Acknowledge and claim actions
• Execute checklists associated with tasks, including capturing evidence in the form of notes, comments, and photo or file attachments
• Surface overdue and unacknowledged items prominently

Evidence captured during checklist execution is stored against the task record in Task Manager and is fully auditable. Task ownership and resolution logic is owned by Task Manager.

5.3 Rotas & Day Awareness

Staff App Mode surfaces the following rota information, sourced from Rota Manager:

• Personal rota and upcoming shifts
• Day lists for clinicians and nurses
• Shift change notifications

Rota data surfaced in Staff App Mode is strictly read-only. Staff cannot alter, override, or submit changes to rota entries through the app; any adjustments are a management-only concern handled via Rota Manager's own interfaces.

Rota Manager as Authoritative Source for Shift Times and Quiet Hours

Rota Manager is the authoritative system of record for shift start and end times per staff member. Staff App Mode consumes this data exclusively via Rota Manager's read-only feed; it does not derive or store its own copy of shift boundaries. Shift start and end times sourced from this feed are the sole input used to determine quiet-hours windows for notification suppression (see §6). Staff App Mode MUST NOT infer, override, or independently calculate a staff member's working hours for notification-suppression purposes; if Rota Manager does not provide a shift record for a given period, the module MUST apply a safe default (suppress non-urgent notifications) until a valid shift signal is received.

5.4 Requests & Submissions

Staff can submit the following request types, all of which are tracked and auditable:

• Holiday and sickness requests
• Shift swap requests
• Errands and admin requests
• Expense claims (with receipt attachments)
• Ideas and improvement suggestions
• Anonymous feedback

5.5 Documents & Policies

Staff App Mode surfaces documents and policies when enabled by the practice. Staff may:

• Access policies and internal knowledge
• Upload documents securely
• Receive and action document acknowledgement prompts

Document Acknowledgement (Authoritative)

Certain documents require formal confirmation of reading, as configured in Document Hub. Where a document requires acknowledgement:

• Staff are presented with a clear pending-acknowledgement prompt when accessing or being directed to that document
• Confirmation of reading is recorded by user, role, and site and surfaced back to Document Hub
• When a document is updated or superseded, any prior acknowledgement is automatically reset and staff are required to re-acknowledge the new version before the pending prompt is dismissed

Pending acknowledgements MUST be surfaced prominently in the staff dashboard so that staff are aware of outstanding obligations without having to navigate to the documents section directly.

5.6 Assisted Form Completion

Staff App Mode surfaces Digital Forms for use in surgery and at the point of care:

• Staff may guide patients through form completion via a structured, guided in-appointment flow
• Where a patient requires assistance, a named staff member may assist in completing and submitting a form on the patient's behalf; such submissions are attributed to that staff member in the audit trail
• Mandatory form items are enforced and cannot be bypassed by staff-assisted flows
• Signature capture is unified within the form flow
• Review of submitted or in-progress forms is available to authorised staff roles

All assisted completions are auditable and traceable to the assisting staff member. Digital Forms owns form ownership, routing, and storage.

5.7 Smart Dashboards — Session-Start Handoff and Navigation

Smart Dashboards is the default post-login landing surface for all authenticated staff sessions. On successful authentication, Staff App Mode resolves the staff member's active context — comprising their UserId, current role, and assigned site(s) as provisioned in Access Manager and enriched by their active shift signal from Rota Manager — and passes this context to Smart Dashboards before rendering the initial view. Smart Dashboards uses this context to compose and return the role-scoped dashboard card set appropriate to that staff member.

Staff App Mode MUST NOT render a generic or unscoped landing screen at session start; the contextualised Smart Dashboards view MUST be the first content surface presented after authentication completes. Where Smart Dashboards cannot resolve a card set (for example, due to a transient integration failure), Staff App Mode MUST display a clearly indicated degraded state rather than silently rendering an empty or stale view.

Dashboard card definitions, alert signal logic, and card-ordering rules remain the sole responsibility of Smart Dashboards. Staff App Mode owns only the rendering of the resolved card set on the mobile surface and the navigation framework that allows staff to move from dashboard cards into the relevant capability sections of the app.

6. Quiet Hours & Work–Life Boundaries (Authoritative)

Notification delivery respects rota-defined working hours sourced from Rota Manager:

• Non-urgent notifications are suppressed off-shift
• Suppressed notifications are queued and made visible when the staff member returns to their next shift
• Urgent messages override quiet hours and are delivered regardless of rota state
• Quiet hours are enforced automatically and are role-agnostic

The module MUST NOT allow quiet hours to be bypassed by any actor except via the Urgent urgency level on a Notification. Quiet hours configuration is a practice-level admin setting managed via the Admin Control Plane.

7. AI Boundaries (Non-Negotiable)

Staff App Mode embeds AI surfaces via AI Assistant (Aiden).

AI MAY:

• Provide role-aware how-to guidance to staff within the app context
• Surface overdue and at-risk work items for human review
• Suggest next-action recommendations to staff

AI MAY NOT:

• Auto-decide on policy-bound actions such as approving or rejecting requests
• Bypass governance, audit, or access checks
• Make commitments on behalf of the practice
• Alter rota data, task ownership, or document acknowledgement status
• Replace required clinical judgement

All AI suggestions surfaced within Staff App Mode MUST be logged, including whether they were acted upon by the staff member, to satisfy the audit requirements in §8.

8. Audit & Compliance

The system MUST log the following events, with actor identity and timestamp, to an immutable audit trail:

• Staff logins and logouts
• Staff mode activation
• Message send and receive
• Document access and uploads
• Document acknowledgements and re-acknowledgements
• Request submissions and status changes
• Task and callback acknowledgements and actions
• Checklist execution and evidence capture
• Assisted form completions, attributed to the assisting staff member
• Moderation and deletion actions
• Session lock, unlock, and forced termination events
• All AI suggestions surfaced to staff, including whether they were accepted or dismissed
• All cross-module events consumed or emitted by this surface

Audit data is immutable and practice-owned. Audit logs MUST be exportable for inspection by authorised practice administrators.

9. Access Control

Access is enforced via Access Manager:

• Role-based access control governs which capabilities and data are visible to each staff role
• Visibility is scoped by site
• Biometric re-authentication is required after session inactivity
• Access is revoked immediately for leavers; revocation applies to the active session without requiring a new login event
• Anonymous or shared sessions are prohibited

MFA is required for initial authentication where configured by the practice. MFA configuration is owned by Access Manager.

Staff roles that may be scoped within the module include Clinician, Nurse/Support Staff, Reception/FOH, Treatment Coordinator, and Manager/Admin, as provisioned in Access Manager.

10. Integration Summary

• Communication Hub — inbound: messaging, announcement, and social feed primitives surfaced in the app
• Task Manager — inbound: task queues, callbacks, and checklists surfaced and actioned via the app; outbound: task acknowledgements and checklist evidence
• Rota Manager — inbound: shift data (including per-staff shift start and end times), day lists, and quiet hours triggers (read-only); authoritative source for all shift-boundary data used in notification suppression
• Appointment Manager — inbound: day awareness signals (read-only)
• Digital Forms — inbound: form rendering; outbound: assisted completion submissions attributed to staff
• Document Hub — inbound: document content and acknowledgement requirements; outbound: acknowledgement confirmations
• Smart Dashboards — inbound: role-scoped dashboard cards and alert signals; default post-login landing surface; context (UserId, role, site) passed outbound at session start to enable card resolution
• Access Manager — inbound: RBAC, role assignments, and session revocation authority
• AI Assistant (Aiden) — inbound: role-aware guidance, at-risk work signals, and next-action suggestions

11. Explicit Non-Goals

• Clinical documentation workflows — would be owned by the PMS if added
• HR record management, payroll, or employment contract authorship — out of platform scope at this tier
• Rota authoring or adjustment — owned by Rota Manager
• Task creation or resolution logic — owned by Task Manager
• Bypassing quiet hours for any actor without Urgent urgency designation
• Exposing any staff feature or mode to patient users

12. Versioning & Governance

This specification is owned by: the Staff App Mode module owner.

Changes to this spec require:

• Review by the MVP module owner
• Impact analysis across all declared related modules (see /propose)
• Version bump (patch / minor / major depending on impact)

All future changes must preserve: strict staff/patient mode separation, role-aware visibility, work–life boundary enforcement, full auditability, and practice ownership of data.

13. Build Contract (Engineering & QA)

13.1 Canonical Data Model

StaffSession (
  UserId               UUID NOT NULL,
  DeviceId             UUID NOT NULL,
  AuthMethod           ENUM(SSO | MFA | LocalPrimoro),
  LoginTimestamp       TIMESTAMPTZ NOT NULL,
  LastActiveTimestamp  TIMESTAMPTZ,
  LogoutTimestamp      TIMESTAMPTZ,
  AuditTrail           IMMUTABLE LOG
)

StaffRequest (
  RequestId            UUID PRIMARY KEY,
  RequestType          ENUM(Leave | Sickness | Expense | Swap | Errand | Idea | Anonymous),
  SubmittedBy          UUID NOT NULL,
  Status               ENUM(Submitted | UnderReview | Resolved | Cancelled),
  CreatedAt            TIMESTAMPTZ NOT NULL,
  LastUpdatedAt        TIMESTAMPTZ,
  AuditLog             IMMUTABLE LOG
)

Notification (
  NotificationId       UUID PRIMARY KEY,
  RecipientUserId      UUID NOT NULL,
  SourceModule         TEXT NOT NULL,
  Urgency              ENUM(Normal | Urgent),
  Delivered            ENUM(Delivered | Suppressed),
  Timestamp            TIMESTAMPTZ NOT NULL
)

13.2 Core Behaviour Rules

1. Staff mode is hidden and requires an explicit activation gesture; it is not discoverable by patient users.
2. The hidden activation gesture MUST be evaluated and passed before any staff authentication screen is presented; the authentication surface is not reachable without it.
3. Staff and patient modes are mutually exclusive; they cannot coexist within a single session.
4. Logging out fully clears staff access and terminates the StaffSession.
5. Server-side role or access changes apply immediately to the active session.
6. Quiet hours are enforced automatically via rota data from Rota Manager; non-urgent notifications are suppressed off-shift. Rota Manager is the sole authoritative source for shift start and end times used in quiet-hours calculation.
7. Where Rota Manager provides no shift record for a given period, the module MUST apply a safe default and suppress non-urgent notifications until a valid shift signal is received.
8. Urgent notifications override quiet hours and are delivered regardless of rota state.
9. All staff actions are auditable; the audit trail is immutable and practice-owned.
10. Access is revocable instantly for leavers; revocation applies without requiring a new login event.
11. Rota data is read-only; staff cannot alter or submit rota changes via the app.
12. All practice data stored locally on the device MUST be encrypted at rest using device-level encryption controls, regardless of MDM status.
13. Anonymous requests MUST NOT surface the submitter's identity to any reviewing actor.
14. Document acknowledgements are reset automatically when a document is updated or superseded.
15. Smart Dashboards is the default post-login landing surface; Staff App Mode MUST pass resolved user context (UserId, role, assigned site(s)) to Smart Dashboards at session start before rendering the initial view.
16. Locums authenticate via local Primoro credentials scoped to their scheduled shifts; they do not require organisational SSO.
17. All AI suggestions surfaced within the app are logged, including whether they were acted upon.

13.3 Configuration Surfaces

Practice-level settings (Admin Control Plane):

• Role permissions
• Quiet hours behaviour
• Request types enabled
• Document visibility
• Document acknowledgement requirements
• Feed moderation rules
• MFA requirement

Per-user preferences (Access Manager):

• Provisioning, role assignment, and de-provisioning of staff users including locums

Per-object overrides are not applicable in this module; all configuration is practice-level or identity-level.

13.4 Filtering & Views

Staff filters:

• Role queue
• Request status
• Task urgency
• Unread updates

Manager filters:

• Team
• Overdue items
• Pending acknowledgements

13.5 Module Extension Map

The following modules, when enabled, extend Staff App Mode without breaking this contract:

• HR & Compliance — additional request types surfaced in the submission flow
• AI Guardian — sentiment and risk detection across staff communications
• Governance Reporting — staff engagement trend data surfaced to managers
• Knowledge, Training & Learning — surfaces assigned courses, learning pathway progress, and CPD evidence uploads within Staff App Mode; learning tasks are executed via Task Manager and appear in the staff task queue

13.6 Acceptance Criteria

The build of Staff App Mode is complete when:

• [ ] Staff mode is hidden and requires explicit activation; patient users cannot discover it
• [ ] The hidden activation gesture is evaluated and passed before any staff authentication screen is presented
• [ ] Staff and patient modes are mutually exclusive and cannot coexist
• [ ] All authentication paths (SSO, MFA, local Primoro for locums) work correctly
• [ ] Session auto-lock and biometric/PIN re-authentication function correctly
• [ ] Server-side access revocation applies immediately to active sessions
• [ ] Quiet hours suppress non-urgent notifications off-shift using shift start/end times sourced exclusively from Rota Manager; urgent messages override correctly
• [ ] Safe-default suppression applies when Rota Manager provides no shift record for a given period
• [ ] Suppressed notifications are queued and surface on the staff member's return
• [ ] All request types can be submitted, tracked, and audited; anonymous requests do not expose submitter identity
• [ ] Rota view is read-only and staff cannot submit rota changes
• [ ] Document acknowledgements are surfaced prominently, recorded correctly, and reset on document update
• [ ] Assisted form completions are attributed to the assisting staff member in the audit trail
• [ ] Smart Dashboards is the default post-login landing surface; resolved user context is passed at session start and a degraded state is rendered correctly on integration failure
• [ ] Communication Hub Chat and Channel primitives render correctly on mobile and are subject to quiet hours enforcement
• [ ] Local device storage is encrypted at rest regardless of MDM status
• [ ] All integrations in §10 are wired and consuming/emitting correctly
• [ ] All AI suggestions are logged with acceptance/dismissal attribution
• [ ] AI boundaries in §7 are enforced (negative tests pass)
• [ ] Audit log captures every event listed in §8
• [ ] Access control is enforced per §9
• [ ] All non-functional requirements in §14 are met

14. Non-Functional Requirements

• Performance: Login and initial dashboard load MUST complete within an acceptable threshold on a standard mobile connection; background refresh MUST not block the UI thread. Specific latency targets to be defined with engineering before build sign-off.
• Reliability: No practice data may be lost due to connectivity loss; queued notifications MUST be delivered correctly on reconnection. The app MUST degrade gracefully when offline, surfacing cached content where available and clearly indicating connectivity state to the user.
• Scalability: The module MUST support multi-site practices where staff may be assigned to one or more sites, with visibility correctly scoped to the staff member's assigned sites. Multi-tenancy isolation MUST ensure that no data from one practice is accessible to users of another.
• Security: All practice data in transit MUST be encrypted. All practice data stored locally on the device MUST be encrypted at rest using device-level encryption controls, regardless of MDM status. This applies to cached messages, task data, documents, and all other practice content written to device storage. Strict RBAC is enforced via Access Manager. The implementation MUST be MDM-friendly.
• Privacy: The module MUST honour applicable data subject rights. Local device storage MUST be fully clearable on staff offboarding. Anonymous feedback submissions MUST be structurally incapable of identifying the submitter. Retention periods for audit logs and request data to be defined in the platform-level data retention policy.
• Observability: The module MUST export structured logs for all audit events listed in §8. Session and authentication metrics MUST be available for monitoring. Notification delivery and suppression rates MUST be observable. Errors in cross-module integration calls MUST be traceable.
• Accessibility: The mobile interface MUST use large touch targets and sufficient contrast ratios appropriate for a mobile-first clinical staff context. Accessibility baseline to be confirmed against platform-level accessibility standards before build sign-off.

15. Open Questions

1. What are the specific session inactivity timeout values for auto-lock, and are these configurable per practice or fixed platform-wide? (implied by §4.2 — not yet defined)
2. What is the specific latency target for login and dashboard load? (§14 notes this is to be defined with engineering)
3. What is the platform-level data retention policy for audit logs and StaffRequest records? (§14 references a platform-level policy that has not yet been defined)
4. Are document acknowledgement requirements configured entirely within Document Hub, or does Staff App Mode expose any local configuration for acknowledgement behaviour? (implied ambiguity in §5.5)
5. For multi-site staff, is site-scoped visibility driven automatically by the active shift in Rota Manager, or does the staff member manually select a site context within the app? (§9 references site-scoped visibility but the selection mechanism is not specified)
6. What is the precise definition of the "hidden activation gesture" for staff mode entry, and is this gesture configurable or fixed? (referenced in §4.1 but not specified)