Admin Control Plane – UX Specification

Related Technical Authority: Admin Control Plane – Technical Specification

1. Purpose

This UX specification governs the internal staff experience of the Admin Control Plane (ACP) — Primoro's single operational environment for managing the full SaaS tenant lifecycle. It defines how Primoro staff across roles (SuperAdmin, Provisioning Engineer, Finance Admin, Telephony Admin, Support Engineer, CSM, and Sales) discover, act on, and confirm every significant administrative operation, from prospect intake through to tenant decommissioning. Because every action taken here has downstream consequence for live customer practices, the specification prioritises governance visibility, irreversibility signalling, and unambiguous role-scoped affordances above all other design considerations.

2. Core UX Principles (Non-Negotiable)

These principles take precedence over visual preferences. If a design choice conflicts with a principle below, the principle wins.

• Action-first — users see the action they need next, not abstract status displays.
• Governance always visible — when AI is involved, users always know what AI did and what they're confirming.
• No dead toggles — every UI control either does something or doesn't appear.
• Calm by default — the interface gets out of the way; alerts are reserved for things that genuinely need attention.
• Progressive disclosure — advanced detail is one click away, not always-on.
• Role-scoped affordances — controls that the current user's role cannot invoke are not shown in a disabled state; they are absent entirely, except where their existence must be known for governance reasons (e.g. the regulated-extension toggle is visible but locked for roles below Provisioning Engineer, so that lower-privileged staff understand the capability exists and know who to escalate to). Inferred from technical spec §9 access control rules and §4.5 regulated extension gating.
• Irreversibility always signalled — any action that cannot be undone (decommissioning a tenant, disabling a regulated extension, closing a support session) is visually and textually distinct before the user commits. Inferred from technical spec §3.2 state machine rules, §4.5 Medication & Controlled Drugs confirmation requirement, and §13.2 core behaviour rule 6.
• Audit as first-class UI — the audit trail is not a hidden log; it is a visible, queryable surface accessible without leaving the ACP, so that staff can verify what changed, when, and why without requiring database access. Inferred from technical spec §8 audit requirements and §13.4 audit event log filtering.

3. Design Philosophy

The ACP's mental model is that of a governed operations console, not a general-purpose admin panel. Every screen is scoped to a tenant or to the ACP's own internal operations — there is no global "settings" area that bleeds across concerns. The design reflects the principle stated in the technical spec (§12) that tenant isolation, least-privilege access, and full auditability are non-negotiable invariants, and the UI must make those invariants legible without requiring staff to consult documentation.

Empty states: An empty tenant list, task list, or audit log is an explicit, informative state — it tells the user what they would see here when data exists, and (where role permits) offers a primary action to create the first record. Empty states are never blank screens. Inferred from technical spec §13.4 filter and view requirements.

Error states: Provisioning step failures are surfaced individually, with the failed step named, the recoverable action offered inline, and the audit record of the failure already written. The UI does not ask the user to re-run the entire provisioning flow when a single step failed. Inferred from technical spec §4.4 Tenant Builder idempotency rules and §13.2 rule 5.

AI suggestions: The ACP does not embed AI in its own admin workflows. Where the Telephony Centre surfaces AI Phone Assistant transcription summaries or sentiment analytics, these are presented as AI-generated content with an explicit AI provenance badge, distinct from human-authored data. The admin is never asked to confirm an AI-generated routing decision as if it were their own. Inferred from technical spec §7 AI boundaries.

Multi-step flows: The Onboarding Workflow Engine and the Setup Wizard are the two primary multi-step flows. Both use a stage-gated, sequential step model: the user can see all stages in a progress indicator, can review completed stages, but cannot advance past a validation gate until all required inputs for the current stage are satisfied. Auto-save is active throughout. Inferred from technical spec §4.2 and §4.3.

Undo/redo: Undo is not available for audit-significant actions (state transitions, entitlement changes, support session operations). The correct remediation path is a new, separately audited action. The UI communicates this before the user commits to an irreversible action. For non-audit-significant operations such as drafting onboarding task notes, standard browser-level undo behaviour is acceptable. Inferred from technical spec §13.2 rule 6 (audit write failure causes action rollback) and the immutable audit log requirement in §8.

Read-only vs editable surfaces: Fields that the current user's role cannot edit are rendered as read-only display values, not as disabled form controls. A disabled-looking control invites the user to wonder why it is disabled; a display value communicates that this is information, not an input. The one exception is the regulated-extension toggle (Medication & Controlled Drugs), which is rendered as a locked toggle with a role-requirement label, so its existence and the escalation path are explicit. Inferred from technical spec §4.5 and §9.

4. Primary Surfaces

4.1 Web Portal

Who uses it: all Primoro staff with an ACP admin identity — SuperAdmin, Provisioning Engineer, Finance Admin, Telephony Admin, Support Engineer, CSM, and Sales. Each role sees a role-scoped navigation and role-scoped affordances within each section. Inferred from technical spec §5.1 and §9.

Key tasks performed here:

• Managing the prospect-to-customer pipeline (Admin Pipeline Manager). Inferred from technical spec §4.1.
• Running and monitoring structured onboarding workflows, including task assignment, SLA tracking, and validation-gate progression (Onboarding Workflow Engine). Inferred from technical spec §4.2.
• Completing post-provisioning tenant configuration via the guided Setup Wizard, including the conditional Care Plan Subscriptions step. Inferred from technical spec §4.3.
• Initiating and monitoring tenant provisioning, viewing individual step outcomes, and retrying failed steps (Tenant Builder). Inferred from technical spec §4.4.
• Enabling and disabling module entitlements and feature flags, including regulated extensions, per tenant or per clinic (Entitlement Manager). Inferred from technical spec §4.5.
• Registering, configuring, and health-checking PMS connectors per tenant (PMS Connector Registry). Inferred from technical spec §4.6.
• Managing billing accounts, payment gateway configuration, mandates, and accounting exports (Finance Centre — Finance Admin and SuperAdmin only). Inferred from technical spec §4.7 and §9.
• Provisioning telephony numbers, configuring routing rules and after-hours logic, enabling/disabling the AI Phone Assistant per tenant, and reviewing telephony analytics (Telephony Centre — Telephony Admin and SuperAdmin). Inferred from technical spec §4.8.
• Managing multi-clinic group hierarchies, group-level billing, and cross-site configuration inheritance (Multi-Clinic Group Manager). Inferred from technical spec §4.9.
• Requesting, approving, and monitoring just-in-time support access sessions, including reviewing the full session activity log after expiry (Support Mode). Inferred from technical spec §4.10.
• Monitoring tenant operational health, reviewing active alerts, and triaging auto-generated support tasks (Tenant Health Monitor). Inferred from technical spec §4.11.
• Querying, filtering, and exporting the audit event log (Audit & Compliance surface). Inferred from technical spec §8 and §13.4.
• Configuring role-to-dashboard mappings and widget-set entitlements for Smart Dashboards per tenant (Dashboard Configuration surface). Inferred from Smart Dashboards §4.1 and §13.3.
• Configuring AI Guardian settings per tenant, including enabling or disabling AI Guardian, adjusting detection thresholds, and managing severity mappings (AI Guardian Configuration surface). Inferred from AI Guardian tech spec §13.3.
• Configuring Access Manager settings per tenant, including SSO provider, MFA policy, session timeout, and custom role labels (Access Manager Configuration surface — SuperAdmin and Provisioning Engineer). Inferred from Access Manager §4.1.
• Controlling which Task Manager navigation items are visible and active per tenant, gating items that belong to later delivery phases via feature-flag or entitlement toggles within the Entitlement Manager (Task Manager Navigation Entitlement surface). Where Task Manager defers certain navigation items to a later phase, the ACP is the authoritative surface for enabling those items once the corresponding phase is live. Inferred from Task Manager navigation structure and the Entitlement Manager's general role as the feature-flag control surface (technical spec §4.5). See also Open Question 15.

Layout pattern: the top-level navigation is a persistent left-sidebar or top-nav that organises the functional areas above. Individual functional areas use a list-detail pattern (tenant list → tenant detail), a wizard pattern (Setup Wizard, Onboarding Workflow Engine stage progression), and a dashboard pattern (Tenant Health Monitor, Finance Centre summary views). The audit log uses a filterable table pattern. Inferred from the nature of the functional areas described in technical spec §4 and the filtering requirements in §13.4.

4.2 Tablet App

Not applicable. The technical spec (§5.2) explicitly states the ACP has no tablet delivery surface. This section is intentionally omitted from scope.

4.3 Mobile App (Patient or Staff)

Not applicable. The technical spec (§5.3) explicitly states the ACP has no patient-facing or mobile delivery surface. This section is intentionally omitted from scope.

5. Interaction Model

5.1 Primary Flows

Flow 1: Prospect → Live tenant

Inferred from technical spec §4.1, §4.2, §4.3, §4.4, and the Tenant state machine in §3.2.

1. Sales staff enters or receives a prospect record in the Admin Pipeline Manager.
   └─ Prospect record created; Tenant status = Prospect.

2. Sales staff progresses prospect through qualification stages, capturing notes
   and scoring per pipeline stage.

3. On proposal acceptance (or manual admin initiation), the Onboarding Workflow Engine
   is triggered.
   └─ Tenant status transitions: Prospect → Onboarding.
   └─ Onboarding tasks generated from template; assigned to roles with SLA deadlines.

4. CSM or Provisioning Engineer works through onboarding tasks, stage by stage.
   Each validation gate must be satisfied before the next stage unlocks.
   Digital Forms integration collects required data inline.

5. Provisioning Engineer initiates tenant provisioning via the Tenant Builder.
   └─ Tenant status transitions: Onboarding → Provisioning.
   └─ Discrete provisioning steps execute: tenant record, identity realm, core module
      seed, PMS connector initialisation, communication channel configuration.
   └─ Each step result (success / failure) is displayed individually and written
      to the audit log.

6. If a provisioning step fails:
   └─ Failed step is surfaced individually with a retry action.
   └─ User does not need to re-run the full flow.
   └─ Tenant remains in Provisioning state until all steps pass.

7. All provisioning steps pass → smoke tests execute automatically.
   └─ Smoke test results displayed per test.
   └─ If any smoke test fails: tenant cannot proceed to Live; failed tests
      surfaced individually.

8. All smoke tests pass → Provisioning Engineer or SuperAdmin confirms go-live.
   └─ Confirmation step presented (irreversible; audit event written).
   └─ Tenant status transitions: Provisioning → Live.
   └─ Go-live handoff record generated.

9. Setup Wizard launched for post-provisioning configuration.
   └─ Steps presented in entitlement-aware sequence (Core-first, then conditional
      steps based on active entitlements, e.g. Care Plan Subscriptions step
      rendered only if that entitlement is active).
   └─ Auto-save active throughout; each step validated before progression.
   └─ All configuration changes written to audit log against tenant.

Flow 2: Support Mode — JIT access request and session

Inferred from technical spec §4.10, §3.5 SupportSession object, §9 access control rules, and §8 audit requirements.

1. Support Engineer identifies a tenant requiring access; raises a support session
   request from the tenant detail view.
   └─ Request includes tenant ID and reason.
   └─ Tenant status overlay: pending approval (does not alter primary lifecycle state).

2. SuperAdmin or Provisioning Engineer reviews the pending session request.
   └─ Approval action presented with session duration selector.
   └─ Approval confirmation step (audit event written on confirm; also written
      if the approver declines).

3. On approval:
   └─ SupportSession record created with ExpiresAt timestamp.
   └─ Support Engineer gains scoped access to the tenant.
   └─ Active session indicator visible to all admin roles viewing the tenant.
   └─ Tenant status overlay: Supported.

4. Within the session, every action taken is logged to the session activity log
   in real time (immutable).

5. Session reaches ExpiresAt:
   └─ Access hard-expired; no extension without new approval record.
   └─ Session activity log finalised; summary written to audit log.
   └─ Tenant status overlay: Supported removed.

6. Support Engineer or approver may close the session early via an explicit
   "End session" action (confirmation step presented; audit event written).

Flow 3: Regulated extension toggle (Medication & Controlled Drugs)

Inferred from technical spec §4.5 regulated extension rules, §8 audit event for this toggle, and §9 role restrictions.

1. Provisioning Engineer or SuperAdmin navigates to Entitlement Manager for a tenant.

2. Medication & Controlled Drugs extension toggle is visible to all roles
   but is locked (non-interactive) for roles below Provisioning Engineer.
   Locked state displays a role-requirement label and escalation prompt.

3. Eligible role selects the toggle (enable or disable):

   ENABLING:
   └─ Pre-confirmation warning displayed: activates Controlled Drugs Register,
      enforces immutable CD audit entries, imposes controlled-storage
      configuration requirements.
   └─ Mandatory reason field presented (submission blocked if empty).
   └─ Confirmation action commits the change.
   └─ Entitlement record created; audit event written with actor identity,
      reason, and effective date.
   └─ Finance Centre billing sync triggered.

   DISABLING (after prior active period):
   └─ Pre-confirmation warning displayed: regulatory implications of disabling
      an active Controlled Drugs Register.
   └─ Mandatory reason field presented (submission blocked if empty).
   └─ Confirmation action commits the change (action is logged regardless of
      whether the operator proceeds past the warning).
   └─ Audit event written; Finance Centre billing sync triggered.

Flow 4: Tenant health alert → support task triage

Inferred from technical spec §4.11 Tenant Health Monitor, §6.2 outbound to Task Engine, and §13.4 health dashboard filtering.

1. Tenant Health Monitor detects a threshold breach (PMS sync failure, billing
   issue, telephony degradation, form/workflow error, appointment sync issue).

2. Alert surfaces on the Tenant Health dashboard with alert type, severity,
   affected tenant, and contextual detail.

3. If threshold exceeds auto-task threshold:
   └─ Support task auto-generated in the Task Engine and displayed in the
      admin task list with a link back to the originating alert.

4. CSM or Support Engineer reviews the alert and the linked task.
   └─ Sufficient context to act without requiring direct tenant access.

5. Task actioned and resolved; alert cleared or downgraded.

Flow 5: Smart Dashboards — role-to-dashboard configuration

Inferred from Smart Dashboards §4.1 and §13.3, which state that configuration of role-to-dashboard mappings is performed by Admins via the Admin Control Plane, not via the dashboard surface itself.

1. SuperAdmin or Provisioning Engineer navigates to the Dashboard Configuration
   surface for a specific tenant (accessible from the tenant detail view under
   an "Integrations & Configuration" or equivalent sub-section).

2. The Dashboard Configuration surface presents the full set of roles defined
   for that tenant alongside their currently assigned dashboard layout and
   active widget set.
   └─ Roles with no dashboard assignment are called out explicitly — this is
      an actionable state, not an acceptable blank.

3. Admin selects a role to configure:
   └─ Available dashboard layouts for that tenant are listed (name, description,
      last-modified date).
   └─ Admin assigns or reassigns a layout to the role.
   └─ Admin may adjust the widget-set entitlements active for that role's
      dashboard (enabling or disabling individual widget types).

4. Changes are saved:
   └─ Each role-to-dashboard mapping change is written to the audit log
      (actor, tenant, role, old layout, new layout, timestamp).
   └─ A confirmation toast confirms the mapping has been saved.
   └─ No separate confirmation modal is required unless the change removes a
      layout from a role that currently has active users — in that case an
      inline warning is displayed before the save action is available.

5. Admin may bulk-preview the effective dashboard for any role without
   navigating to the Smart Dashboards surface itself: a read-only preview
   panel renders the layout and widget set as the target role would see it.

Flow 6: AI Guardian — per-tenant configuration

Inferred from AI Guardian tech spec §13.3, which states that practice-level AI Guardian configuration is managed via the Admin Control Plane.

1. SuperAdmin or Provisioning Engineer navigates to the AI Guardian Configuration
   surface for a specific tenant (accessible from the tenant detail view, scoped
   within the Entitlement Manager or as a dedicated sub-section adjacent to it).

2. The surface presents the current AI Guardian state for the tenant:
   └─ Enabled / disabled toggle (subject to entitlement; locked for roles
      below Provisioning Engineer, following the same locked-toggle pattern
      as other regulated entitlements).
   └─ Detection threshold settings (per alert category, where the AI Guardian
      tech spec exposes configurable thresholds).
   └─ Severity mapping overrides (custom mappings from AI Guardian signal
      types to the tenant's local severity vocabulary, where supported).

3. Enabling AI Guardian:
   └─ Pre-confirmation notice displayed summarising what AI Guardian will
      monitor and the audit implications of enabling it.
   └─ Confirmation action commits the change; audit event written with actor
      identity and effective date.

4. Disabling AI Guardian:
   └─ Pre-confirmation warning displayed: AI Guardian monitoring will cease;
      any in-progress alerts will be closed.
   └─ Mandatory reason field presented (submission blocked if empty).
   └─ Confirmation action commits the change; audit event written.

5. Adjusting thresholds or severity mappings:
   └─ Individual threshold or mapping fields are editable inline.
   └─ Changes are saved with a confirm action (not auto-saved, given the
      operational significance of threshold changes).
   └─ Each change is written to the audit log (actor, tenant, field changed,
      old value, new value, timestamp).
   └─ A confirmation toast confirms the save; no full-page reload required.

Flow 7: Access Manager — per-tenant identity and access configuration

Inferred from Access Manager §4.1, which lists configuring SSO provider, MFA policy, session timeout, and custom role labels as key administrative tasks performed via the Admin Control Plane.

1. SuperAdmin or Provisioning Engineer navigates to the Access Manager
   Configuration surface for a specific tenant (accessible from the tenant
   detail view; SuperAdmin and Provisioning Engineer only — other roles see
   this sub-section as absent, per role-scoped affordances principle).

2. The surface is organised into four configuration areas, each independently
   editable:

   SSO CONFIGURATION:
   └─ SSO provider toggle (enabled / disabled).
   └─ When enabled: provider type selector, metadata/endpoint fields, and
      attribute-mapping configuration.
   └─ Changes require a confirm action; audit event written on each save.
   └─ Disabling an active SSO provider surfaces an inline warning that
      affected users will fall back to local authentication.

   MFA POLICY:
   └─ MFA requirement selector (not required / optional / required for all /
      required for elevated roles only — options surfaced as per Access
      Manager's supported policy modes).
   └─ Changes require a confirm action; audit event written.

   SESSION TIMEOUT:
   └─ Configurable idle-session timeout value for the tenant, within bounds
      defined by Access Manager's policy limits.
   └─ Out-of-bounds values are rejected inline with the permitted range shown.
   └─ Changes require a confirm action; audit event written.

   CUSTOM ROLE LABELS:
   └─ The tenant's locally overridden display labels for standard roles are
      shown alongside the canonical role names.
   └─ Admin may edit custom labels per role (free-text, with character limit).
   └─ Canonical role names are shown as read-only reference values beneath
      each custom label field, so that the underlying Access Manager role
      identity is never ambiguous.
   └─ Changes are saved per-role; audit event written per label change.

3. All four areas are independently saveable — the admin does not need to
   complete all four in sequence. Auto-save is NOT active for this surface
   given the security significance of identity configuration; every change
   requires an explicit save action.

4. A configuration summary panel (read-only) is always visible alongside the
   editable areas, reflecting the current effective Access Manager state for
   the tenant. This provides the admin with a at-a-glance view of what is
   active without requiring them to open each area individually.

Flow 8: Communication Hub — per-tenant channel notification policy

Inferred from Communication Hub module, which indicates that channel-level notification behaviour (including the ability to suppress all notifications for a channel) is configurable by admin users, implying an admin-facing configuration surface within the ACP.

1. SuperAdmin or Provisioning Engineer navigates to the Communication Hub
   Configuration surface for a specific tenant (accessible from the tenant
   detail view, as a sub-section within "Integrations & Configuration" or
   equivalent, alongside other per-tenant configuration surfaces).

2. The surface presents the notification policy settings available per
   communication channel for that tenant:
   └─ Per-channel notification suppression toggle (e.g. suppress all
      outbound notifications for a given channel type).
   └─ Where Communication Hub exposes additional channel-level policy modes
      (e.g. digest-only, business-hours-only delivery), these are presented
      as selectable options per channel.
   └─ Controls that the current user's role cannot modify are absent (not
      disabled), per role-scoped affordances principle.

3. Changing a channel notification policy:
   └─ Suppressing all notifications for an active channel surfaces an inline
      warning summarising the downstream effect (e.g. tenant users will
      cease to receive notifications via that channel).
   └─ Changes require a confirm action; audit event written (actor, tenant,
      channel, old policy, new policy, timestamp).
   └─ A confirmation toast confirms the save.

4. The ACP does not configure notification content or delivery channel
   selection for individual notification types — that remains owned by
   Communication Hub. The ACP surface governs only the channel-level policy
   settings that Communication Hub exposes for admin control.
   └─ A read-only summary of Communication Hub's current effective delivery
      configuration for the tenant is displayed beneath the editable policy
      fields, so that the admin can see the full picture without navigating
      to Communication Hub's own portal.

5.2 State Machines (Mirror of Technical Spec § 3.2)

The following describes how each Tenant lifecycle state is represented in the UI. Inferred from technical spec §3.2 Tenant State Machine and §13.2 core behaviour rules.

State badges appear on the tenant list row and in the tenant detail header, so that a user navigating the list can see lifecycle state at a glance without opening the record. Inferred from §13.4 tenant list filter requirements which imply state is a primary filter dimension.

Transitions that require elevated roles (Provisioning → Live, regulated extension toggles) display a role indicator alongside the confirmation action, naming the minimum required role, so that a user who cannot perform the action understands who can. Inferred from §3.2 transition rules and §9 access control.

5.3 Empty / Loading / Error / Offline States

All states below are inferred from the functional areas described in the technical spec and the non-functional requirements in §14.

Tenant list

• Empty state: Displayed when no tenants match the current filter or when no tenants have been created yet. Presents a brief explanation of what will appear here, and (for roles with permission) a primary action to create the first prospect record.
• Loading state: Skeleton rows while the list fetches, preserving the list's column structure so the layout does not shift on load.
• Error state: Inline error message with a retry action. Does not navigate the user away from the list.
• Offline state: The ACP is an internal staff tool delivered via web portal; full offline operation is not a design target. A connectivity-lost banner is shown; the user is informed that the portal requires network access and no actions can be taken until connectivity is restored.

Provisioning step list (Tenant Builder)

• Empty state: Not applicable — provisioning steps are generated at provisioning initiation and always present once the flow has started.
• Loading state: Each provisioning step displays an individual in-progress indicator while it is executing, distinct from pending and completed states.
• Error state: A failed step is displayed inline with a failure reason summary and an individual retry action. The overall provisioning flow does not collapse to a single error page; all other step states remain visible alongside the failed step.
• Offline state: As per tenant list — connectivity-lost banner; no actions permitted.

Onboarding task list

• Empty state: Displayed when no tasks exist for the current filter. If the task list for a specific tenant is empty, this is a positive signal (all tasks complete) and is presented as such.
• Loading state: Skeleton rows.
• Error state: Inline error with retry.
• Offline state: Connectivity-lost banner; read-only cached view of task list where technically feasible, but no state changes permitted.

Audit event log

• Empty state: Displayed when no events match the current filter. Prompts the user to adjust filter criteria.
• Loading state: Skeleton rows; the log can be large so progressive loading (pagination or virtual scroll) is expected.
• Error state: Inline error with retry. The log is read-only; no user data is at risk.
• Offline state: Connectivity-lost banner; log not accessible offline.

Tenant Health dashboard

• Empty state: Displayed when no alerts are active. This is a positive state — explicitly communicated as "no active alerts" rather than a blank panel.
• Loading state: Skeleton cards or rows per alert category.
• Error state: If the health monitor data cannot be fetched, the dashboard displays a degraded-state notice distinguishing between "no alerts" and "alert status unavailable". A staff member must not assume "no alerts" when the monitor itself is unreachable.
• Offline state: Connectivity-lost banner; last-known alert state may be shown with a staleness timestamp if technically feasible, clearly labelled as potentially out of date.

Support Mode session view

• Empty state: No active session for this tenant — displays the request-session action for eligible roles.
• Loading state: Spinner while session approval status is fetched.
• Error state: Inline error if session request submission fails, with retry.
• Offline state: Connectivity-lost banner; session state changes not permitted.

6. Component Inventory

New components introduced or extended by this module:

• Tenant status badge — displays the current Tenant lifecycle state (Prospect, Onboarding, Provisioning, Live, Suspended, Decommissioned, etc.) as a labelled badge with semantic colour. Appears on tenant list rows and tenant detail headers. Inferred from §3.2 state machine and §13.4 list views.
• Provisioning step card — displays an individual provisioning step with its execution state (pending / in-progress / succeeded / failed), a result summary, and (when failed) an inline retry action. Appears in the Tenant Builder view. Inferred from §4.4 and §13.2 rule 5.
• Regulated-extension toggle — a toggle control that is rendered in a locked state with a role-requirement label for users below the required role, and as an interactive toggle for Provisioning Engineer and SuperAdmin. Triggers the mandatory-reason confirmation flow on interaction. Appears in the Entitlement Manager and the AI Guardian Configuration surface. Inferred from §4.5.
• Mandatory-reason confirmation modal — a confirmation dialog that includes a required free-text reason field, a consequence summary, and a labelled irreversibility warning. Used for regulated extension toggles, go-live confirmation, decommissioning, support session approval, and disabling AI Guardian. The submit action is disabled until the reason field is non-empty. Inferred from §4.5, §3.2, and §8 mandatory Reason field rules.
• Support session indicator — an overlay badge on the tenant detail header indicating an active support session, including the session owner, the time remaining until expiry, and (for eligible roles) an "end session" action. Inferred from §4.10 and §3.5.
• Onboarding stage progress indicator — a horizontal or vertical stage-by-stage progress display showing completed, active, and locked stages with SLA status per stage. Appears in the Onboarding Workflow Engine view. Inferred from §4.2.
• Setup Wizard step navigator — a step-by-step progress control showing the ordered configuration steps, their completion status, and a visual indicator for conditional steps (e.g. the Care Plan Subscriptions step appears only when that entitlement is active). Inferred from §4.3.
• AI provenance badge — a small inline label identifying content generated by the AI Phone Assistant (e.g. call transcription summaries, sentiment analytics) as AI-generated, distinct from human-authored records. Appears in the Telephony Centre analytics views. Inferred from §7 AI boundaries and §7 audit Actor field rules.
• Audit event log row — a table row rendering a single AdminAuditEvent record with event type, actor, target tenant, timestamp, old value, new value, and reason (where present). Includes an expand action for full structured detail. Inferred from §8 and §13.4 audit event log filter requirements.
• Tenant health alert card — displays a single health alert with alert type, severity, affected tenant, contextual detail, and a link to the auto-generated support task (where one exists). Appears in the Tenant Health Monitor dashboard. Inferred from §4.11.
• Dashboard role-mapping row — a table row within the Dashboard Configuration surface displaying a role name, its currently assigned layout, and its active widget-set entitlements, with inline edit controls for eligible roles. Includes a read-only preview action. Inferred from Smart Dashboards §4.1 and §13.3.
• Configuration summary panel — a read-only side panel surfacing the effective current state of a multi-area configuration surface (used in the Access Manager Configuration surface and the Communication Hub Configuration surface). Allows the admin to see all active settings at a glance without opening each configuration area individually. Inferred from Access Manager §4.1 and Communication Hub module.
• Channel notification policy row — a table row or card within the Communication Hub Configuration surface displaying a communication channel, its current notification suppression state, and any additional policy mode settings exposed by Communication Hub for admin control. Includes inline edit controls for eligible roles and a confirm action. Inferred from Communication Hub module.

Reused from the design system:

• Filterable data table (used for tenant list, task list, entitlement view, support session log, audit event log, dashboard role-mapping view). Inferred from §13.4 filtering requirements.
• Form field with programmatic label (used throughout Setup Wizard, onboarding task forms, pipeline entry, AI Guardian threshold fields, Access Manager configuration fields, Communication Hub channel policy fields). Inferred from §4.1–4.3.
• Toast notification (used for non-critical confirmations such as auto-save completion, task status updates, dashboard mapping saves, AI Guardian threshold saves, and Communication Hub channel policy saves). Inferred from §5.4 engagement signals and Communication Hub integration.
• In-app banner (used for connectivity-lost state and active-session warnings). Inferred from §5.1 and offline state requirements.
• Skeleton loader (used across all list and table surfaces). Inferred from loading state requirements across §5.3.

7. Visual Design Notes

• Semantic colour usage: Tenant lifecycle state badges use semantic colour: neutral for Prospect/Onboarding, a cautionary treatment for Provisioning, a positive treatment for Live/Billed, a warning treatment for Suspended, a muted/archived treatment for Decommissioned. The Supported state overlay uses a distinct informational treatment that does not visually override the primary state colour. Inferred from §3.2 state machine and the governance-visible principle.
• AI content distinction: AI-generated content (Telephony Centre transcription summaries, sentiment analytics) uses a visually distinct container treatment — for example, a differentiated border style or background tint — combined with the AI provenance badge, so that human-authored and AI-generated data are never visually equivalent. Inferred from §7 AI boundaries and the governance-visible principle.
• Irreversibility distinction: Confirmation modals for irreversible actions (go-live, decommission, regulated extension toggle, AI Guardian disable) use the error/warning semantic colour for the action button and consequence summary, not the standard primary action colour. This is a deliberate choice to slow the user down, not to imply an error has occurred. Inferred from §4.5 and §13.2 rule 6.
• Monospace usage: Audit event detail views — including OldValue, NewValue, structured metadata, and session activity logs — are rendered in a monospace typeface to aid scannability of structured data. Inferred from §8 and §13.1 data model (JSONB fields).
• Typography scale, exact colour values, iconography set, and motion timing: (needs UX writer input — to be defined by the design system in alignment with the broader Primoro internal tooling visual language)

8. Accessibility & Inclusivity

The module MUST meet WCAG 2.2 AA. Specifically:

• Text contrast ≥4.5:1 (normal) / ≥3:1 (large)
• All interactive controls reachable via keyboard
• Focus states visible
• Form fields have programmatic labels
• ARIA used only where native semantics are insufficient
• Touch targets ≥44×44 px on mobile/tablet
• Motion can be reduced via prefers-reduced-motion
• Screen reader tested on NVDA and VoiceOver (primary targets for an internal staff web portal)

Mandatory-reason fields: The mandatory-reason field in confirmation modals for regulated actions MUST have a programmatic label, an aria-required="true" attribute, and an inline validation message that is announced to screen readers when submission is attempted with an empty field. The consequence of submitting without a reason (action blocked at write time) is too significant to rely on visual-only feedback. Inferred from §8 and §13.2 rule 7 (audit entry rejected if Reason absent).

Audit log table: The audit event log is a large, dense data table. It MUST use proper <table> semantics with <th scope="col"> headers and <caption>, and row-expansion for detailed structured values MUST be keyboard-accessible and announced to screen readers. Inferred from §13.4 audit event log requirements.

Session expiry countdown: The support session timer (time remaining until ExpiresAt) MUST NOT rely solely on a visual countdown. An accessible text equivalent MUST be present, and an approaching-expiry warning MUST be surfaced as an in-app notification that screen readers will encounter in the natural reading flow. Inferred from §4.10 hard session expiry requirement.

9. Internationalisation

Locale-aware date/time/number formatting.

All user-facing strings externalised.

Layouts tolerant of 30% string-length growth (German, French).

RTL support: not required for the initial build. The ACP is an internal Primoro staff tool; the initial staff user base does not include RTL-script locales. This assumption should be revisited if Primoro expands its internal operations team internationally. Inferred from the internal, non-customer-facing nature of the ACP stated in §1 and §5.1.

UTC timestamps: all timestamps in the ACP are stored in UTC (per §13.1 data model). The UI MUST render timestamps in the current admin user's local timezone with the UTC offset displayed, so that audit records are unambiguous across regions. This is particularly important for SupportSession ExpiresAt values and OnboardingTask SLA deadlines. Inferred from §13.1 TIMESTAMPTZ fields and the multi-region scope stated in §3.1.

10. Cross-Module UX Touchpoints

Where this module's UX intersects with related modules:

• Access Manager — the ACP consumes admin identity and role data from Access Manager. The role indicator visible in the ACP header (current user's role and active permissions) reflects Access Manager's authoritative role assignments. Role management for ACP staff is performed via an Access Manager surface reachable from within the ACP (SuperAdmin only). There is no visual discontinuity between the ACP and the Access Manager role-assignment surface; it appears as an ACP sub-section. Per-tenant Access Manager configuration (SSO, MFA, session timeout, custom role labels) is managed via the Access Manager Configuration surface within the tenant detail view, as described in Flow 7. Inferred from §6.1 inbound integration, §9 role table, and Access Manager §4.1.
• Task Engine — auto-generated support tasks and onboarding tasks are surfaced within the ACP's own task list views, not by navigating to a separate Task Engine portal. The ACP task list is a projection of Task Engine records scoped to ACP-originated tasks. Inferred from §6.2 outbound to Task Engine and §4.11.
• Task Manager — the ACP's Entitlement Manager governs which Task Manager navigation items are active per tenant. Where Task Manager defers certain navigation items to later delivery phases, the ACP surfaces the corresponding feature-flag toggles so that a SuperAdmin or Provisioning Engineer can enable those items once the relevant phase is live. The Task Manager navigation entitlement view follows the same locked-toggle pattern as other feature-flag surfaces: items gated to a future phase are visible as locked, with a label indicating their phase dependency, so that staff understand what is coming without being able to activate it prematurely. Inferred from Task Manager navigation structure and the Entitlement Manager's role as the feature-flag control surface (technical spec §4.5). See also Open Question 15.
• Digital Forms — during the Onboarding Workflow Engine and the Setup Wizard, data collection steps are rendered inline using Digital Forms. The admin does not navigate away from the ACP to complete a form; the form is embedded in the current step. On completion, the form data is returned to the ACP workflow. Inferred from §4.2, §4.3, and §6.1 inbound from Digital Forms.
• Communication Hub — the ACP does not send notifications directly. When a tenant lifecycle event (e.g. go-live, billing failure) triggers a notification, the ACP emits an event to Communication Hub, which owns delivery. The ACP admin may see a confirmation that the notification event was emitted, but does not configure notification content or delivery channel from within the ACP. Per-tenant channel-level notification policy settings (such as notification suppression per channel) that Communication Hub exposes for admin control are managed via the Communication Hub Configuration surface within the tenant detail view, as described in Flow 8. Inferred from §6.2 outbound to Communication Hub, §2.2 explicit non-responsibilities, and the Communication Hub module.
• Audit & Compliance — the ACP's internal audit event log is a filtered view of the events the ACP emits to Audit & Compliance. For deep compliance inspection or cross-module audit queries, admin staff are directed to the Audit & Compliance module's own portal. The ACP surface provides operational-level audit visibility (recent events for a given tenant, session logs) without duplicating the full compliance reporting capability. Inferred from §6.2 outbound to Audit & Compliance and §8.
• Finance Centre — entitlement changes in the Entitlement Manager trigger billing sync events to Finance Centre. The ACP Entitlement Manager surface confirms to the admin that a billing sync has been triggered but does not expose billing account detail inline; Finance Admin roles navigate to the Finance Centre section of the ACP for full billing management. Inferred from §4.5, §4.7, and §9 Finance Admin role scope.
• Inventory & Compliance Manager — the Medication & Controlled Drugs extension toggle in the Entitlement Manager is the ACP's only UX touchpoint with this module. The ACP does not surface Inventory & Compliance Manager operational screens; it only controls whether the extension is entitled. Inferred from §10 integration summary.
• Care Plan Subscriptions — the Setup Wizard conditional step for Care Plan Subscriptions is rendered only when that entitlement is active. The ACP does not surface Care Plan Subscriptions operational screens. Inferred from §4.3 and §13.2 rule 12.
• AI Phone Assistant — the Telephony Centre section of the ACP surfaces AI Phone Assistant enablement toggles, routing configuration, and analytics summaries (including AI-generated transcription and sentiment data). The admin does not navigate to a separate AI Phone Assistant portal for these tasks. Inferred from §4.8 and §7 AI boundaries.
• Security & Privacy — the ACP's audit records conform to the canonical SecurityEvent model defined by Security & Privacy. From a UX perspective, this means the audit event log uses the canonical EventType vocabulary (extended with ACP-specific types), and any future change to the canonical model that alters field names or required fields MUST be reflected in the ACP audit log display. There is no user-navigable Security & Privacy surface within the ACP; the relationship is a data contract. Inferred from §8 and §6.2 outbound to Security & Privacy.
• Smart Dashboards — role-to-dashboard layout mappings and widget-set entitlements for each tenant are configured exclusively within the ACP's Dashboard Configuration surface; the Smart Dashboards product surface itself does not expose these controls. The admin does not navigate to a separate Smart Dashboards portal to manage role assignments. Inferred from Smart Dashboards §4.1 and §13.3.
• AI Guardian — per-tenant AI Guardian configuration (enable/disable, detection thresholds, severity mappings) is managed within the ACP's AI Guardian Configuration surface, accessible from the tenant detail view. The ACP does not surface AI Guardian's operational alert stream; it controls only whether AI Guardian is entitled and how it is calibrated for the tenant. Inferred from AI Guardian tech spec §13.3.

UX consistency rules:

• The current user's role is always visible in the ACP portal header. This is non-negotiable given the governance stance of the module — admin staff must be able to confirm at a glance which role they are operating under, particularly in contexts where role determines whether a given action is available. Inferred from §9 access control rules and the governance-visible principle.
• Confirmation modals for irreversible or elevated-role actions follow a single consistent pattern across all functional areas: consequence summary, mandatory-reason field (where required), clearly labelled action buttons distinguishing confirm from cancel. This pattern must not vary between the Entitlement Manager, the Tenant Builder go-live step, the Support Mode approval flow, the decommissioning flow, the AI Guardian disable flow, the Access Manager SSO-disable warning, and the Communication Hub channel notification suppression warning. Inferred from §4.5, §4.4, §4.10, and §3.2.
• Audit event log entries linked from a specific tenant context (e.g. from the tenant detail view) open pre-filtered to that tenant. Audit event log entries linked from a specific support session open pre-filtered to that session. The user does not arrive at an unfiltered global log and have to manually re-apply context. Inferred from §13.4 filtering requirements and the action-first principle.

11. Governance & Auditability

The following governance treatments are applied throughout the ACP. Inferred collectively from technical spec §8 audit requirements, §7 AI boundaries, §9 access control, and §4.5 regulated extension rules.

• AI content is visually distinct from human-authored content throughout the Telephony Centre analytics surfaces. AI-generated call transcription summaries and sentiment analytics are marked with an AI provenance badge and rendered in a visually differentiated container. An admin reviewing telephony data must never be in doubt about whether they are reading a human note or an AI-generated summary. Inferred from §7 AI boundaries and the governance-visible principle.
• Every audit-significant action shows a confirmation step before it is committed. The confirmation step names the action, identifies the target tenant, summarises the consequence, and (where required) requires a non-empty reason field. The confirm action is visually distinct from the cancel action. This applies equally to configuration changes in the Dashboard Configuration, AI Guardian Configuration, Access Manager Configuration, and Communication Hub Configuration surfaces. Inferred from §8 mandatory audit events and §13.2 rule 7.
• The current user's role and active permissions are visible in the portal header at all times. Where a user attempts to access a capability outside their role, the response is not a generic "access denied" page but a contextual message naming the minimum required role and the escalation path. Inferred from §9 role table and the governance-visible principle.
• Read-only states are visually distinct from editable states. Fields the current user cannot edit are rendered as display values, not disabled inputs. The regulated-extension toggle is the one deliberate exception: it is rendered as a recognisable toggle control in a locked state with a role-requirement label, so that the capability is discoverable and the escalation path is legible. The same locked-toggle treatment is applied to the AI Guardian enable/disable control for roles below Provisioning Engineer, and to Task Manager navigation items that are gated to a future delivery phase. Inferred from §4.5 and §9.
• The audit event log is surfaced as a first-class operational screen, accessible from the main navigation and from individual tenant detail views (pre-filtered to that tenant). Admin staff do not need to request a database export to review recent audit activity for a tenant. The log is exportable to CSV or structured format for compliance inspection. Inferred from §8 exportability requirement and §13.4 audit event log filter requirements.
• Support session activity is visible to all admin roles who can view the tenant record, not only to the session owner or the approver. The active session indicator on the tenant detail header communicates who has access, under what session, and when that access expires. This ensures no admin action against a tenant is invisible to other staff with appropriate access. Inferred from §4.10 and the governance-visible principle.
• Provisioning step outcomes are individually visible in the Tenant Builder view. A partially provisioned tenant does not present a single "failed" state; it presents each step's individual outcome so that staff can see exactly what succeeded, what failed, and what has not yet been attempted. Inferred from §4.4 and §13.2 rule 5.

12. Notification & Communication Patterns

The ACP does not deliver notifications directly to end users. All external notification delivery (email, SMS, push) is routed through Communication Hub. The following in-product patterns are used within the ACP web portal itself. Inferred from §6.2 outbound to Communication Hub and the engagement signals described in §5.4.

• In-app banner — used for connectivity-lost state (persistent, full-width, cannot be dismissed until connectivity is restored) and for active support session warnings visible to all admin roles on the affected tenant's detail view. Inferred from offline state requirements and §4.10 session visibility.
• Toast — used for non-critical confirmations: auto-save completion in the Setup Wizard and Onboarding Workflow Engine, successful task status updates, non-urgent billing sync confirmation, dashboard role-mapping saves, AI Guardian threshold saves, and Communication Hub channel policy saves. Toasts are time-limited and do not require user dismissal. They are not used for audit-significant events, which require the user to actively confirm before the action completes. Inferred from §4.2, §4.3, and the calm-by-default principle.
• In-page alert / inline notification — used for provisioning step failures (surfaced inline on the step card, not as a global banner), smoke test failures, SLA-breach warnings on onboarding task lists, and out-of-bounds threshold values in AI Guardian configuration. These are persistent until resolved and include an action the user can take. Inferred from §4.4, §4.2, and §13.2 rule 5.
• Push notification (via Communication Hub) — the ACP emits events to Communication Hub for tenant lifecycle state transitions (e.g. go-live completion, billing failure). Communication Hub owns delivery channel selection and timing. The ACP does not configure notification content or delivery preferences from its own UI. Inferred from §6.2 outbound to Communication Hub.
• Email/SMS (via Communication Hub) — same as push: the ACP emits the event; Communication Hub owns delivery. Inferred from §6.2.
• Approaching session expiry warning — a dedicated in-app notification surfaced to the active Support Engineer and the approving admin when a support session is approaching its ExpiresAt timestamp. The warning includes the time remaining and the re-approval path if continued access is needed. This is surfaced as an in-app banner on the session view rather than a dismissible toast, given its operational significance. Inferred from §4.10 hard expiry requirement and the governance-visible principle.

13. Open Questions

UX decisions to resolve before this spec is promoted from draft to published. Items 1–8 are carried through from the technical spec's open questions (§15) where they have UX implications; items 9 onwards are UX-specific additions.

• (1) Provisioning SLA target — the go-live progress indicator and any SLA-breach warning in the Provisioning state cannot be designed until the end-to-end provisioning SLA is defined. Carried from technical spec open question 1.
• (2) Tenant count and throughput — the tenant list pagination strategy and virtual-scroll approach depend on the maximum projected tenant count. Carried from technical spec open question 2.
• (3) Audit log retention period — the audit event log UI should indicate how far back records are retained, and offer an appropriate "older records may have been archived" message at the boundary. Cannot be designed until retention period is defined. Carried from technical spec open question 3.
• (6) Tenant Suspended state — the visual treatment, confirmation pattern, and role gating for the Suspended state badge and the unsuspend action cannot be fully specified until the trigger rules and role requirements are defined. Carried from technical spec open question 6.
• (7) Decommissioning procedure — the confirmation modal for tenant decommissioning needs to surface which downstream artefacts (PMS tokens, billing mandates, telephony numbers) will be actively revoked versus flagged. This content cannot be authored until the decommissioning procedure is defined. Carried from technical spec open question 7.
• (needs UX writer input — exact microcopy, button labels, and consequence summary text for all mandatory-reason confirmation modals: go-live, decommission, regulated extension enable/disable, support session approval and early closure, AI Guardian disable, Communication Hub channel notification suppression)
• (needs UX writer input — empty state messaging for the tenant list, onboarding task list, audit event log, tenant health dashboard, and Dashboard Configuration surface: what does each surface say to a user who has arrived before any data exists?)
• (needs UX writer input — approaching-expiry warning copy for support sessions: what does the admin see at, for example, 15 minutes and 5 minutes before ExpiresAt? What is the re-approval prompt?)
• (9) Role indicator placement — the governance-visible principle requires the current user's role to be visible in the portal header at all times. The exact placement and visual treatment of the role indicator relative to the user identity display needs resolution with the design system team, particularly to ensure it does not clash with breadcrumb navigation on nested tenant views.
• (10) Audit log export format — the technical spec (§8) states the log must be exportable to "CSV or structured format". The UX needs to define whether this is a synchronous download (suitable for small filtered result sets) or an asynchronous export job (required for large date-range exports), and what the admin sees while an async export is preparing.
• (11) Multi-clinic group hierarchy visualisation — the Multi-Clinic Group Manager governs tenant hierarchies with clinic inheritance. The UX for visualising and editing a group hierarchy (tree view, list-indent, or flat table with parent reference) has not been defined and should be resolved before the Multi-Clinic Group Manager section of the ACP is built.
• (needs UX writer input — locked regulated-extension toggle label: what does the role-requirement label say to a Support Engineer or CSM who encounters the Medication & Controlled Drugs toggle in its locked state? The text must name the required role and offer a clear escalation path without being alarming.)
• (12) Dashboard Configuration — layout preview scope — Flow 5 describes a read-only preview panel that renders the effective dashboard for a given role. It is not yet resolved whether this preview is a live render of the Smart Dashboards surface (requiring cross-module embedding) or a static representation sufficient for configuration review. This should be resolved with the Smart Dashboards team before the Dashboard Configuration surface is built.
• (13) AI Guardian threshold bounds and display — the AI Guardian Configuration surface (Flow 6) surfaces configurable thresholds and severity mappings. The permitted ranges, default values, and field types for these settings are owned by the AI Guardian tech spec. The UX cannot be fully implemented until AI Guardian confirms the complete set of configurable parameters and their constraints.
• (14) Access Manager configuration surface placement — Flow 7 places the Access Manager Configuration surface within the tenant detail view. It is not yet resolved whether SSO and MFA configuration should instead sit within a dedicated "Security" sub-section of the tenant detail, separate from other configuration areas, to reflect the elevated sensitivity of identity settings. This should be resolved with the Access Manager and design system teams before implementation.
• (15) Task Manager phase-gating scope and UI — the ACP's Entitlement Manager is identified as the control surface for enabling Task Manager navigation items that are deferred to later delivery phases. The full list of phase-gated items, the conditions under which each becomes activatable, and whether enabling them requires a confirmation step (and audit event) has not yet been confirmed by the Task Manager team. This must be resolved before the Task Manager Navigation Entitlement view within the Entitlement Manager is built. Until confirmed, the locked-toggle pattern (visible but non-interactive, with a phase-dependency label) should be treated as the default assumption.
• (16) Communication Hub channel policy scope — Flow 8 and the Communication Hub Configuration surface assume that Communication Hub exposes a defined set of channel-level policy settings for admin control (e.g. suppression toggles, delivery mode selectors). The complete set of configurable parameters, their permitted values, and which roles may modify them has not yet been formally confirmed by the Communication Hub team. This must be resolved before the Communication Hub Configuration surface is built. Until confirmed, the surface should be treated as a placeholder within the tenant detail view.