Communication Hub – UX Specification

Related Technical Authority: Communication Hub – Technical Specification

1. Purpose

This UX specification governs the staff and patient communication experience within Communication Hub. It defines how conversation threads, channels, announcements, praise, acknowledgements, structured internal requests, and message-to-work conversion are presented and enforced across the Web Portal, Tablet App, and Patient Mobile App. The module serves staff in all roles as primary users, with managers and administrators as oversight and configuration users, and patients as a constrained secondary audience, inferred from Technical Spec §5 delivery surface matrix and §2.1 responsibilities. It exists to replace ungoverned, ad-hoc communication (such as informal messaging applications) with auditable, role-owned, work-generating surfaces.

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 are 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.
• Operational first, not fragile — conversations may feel chat-like, but nothing important may be hidden, forgotten, or left unmanaged. Messages that represent work must be captured as work. Derived from Technical Spec §4.1 and §4.5, which require message-to-work conversion and prohibit silent loss of intent.
• Everything has ownership — users must always be able to see who owns a thread and what happens next. Derived from Technical Spec §3.1 OwnerRole requirement and §3.2 state machine rules — ownership is role-first and must be unambiguous at all times.
• Chat ≠ work, but chat can create work — free-text chat is permitted; when intent implies a task, issue, or request, the system must surface a conversion path. Derived from Technical Spec §4.1 and §4.5 message-to-work conversion requirement.
• Role-first, not person-first — channels and threads are owned by roles or governed groups, not individuals. Responsibility persists beyond a single person. Derived from Technical Spec §3.2 rule: "Ownership is role-first; there are no personal inboxes."
• Human tone for internal comms (explicitly allowed) — internal staff conversations may use chat-style tone and lightweight social cues. Patient-facing and external conversations must remain professional and policy-safe. Derived from Technical Spec §4.1 which permits staff chat but contrasts with patient-facing thread context rules.
• No group sprawl — ad-hoc, ungoverned group chats must be discouraged; group-based communication must occur in named, governed channels. Derived from Technical Spec §1 which explicitly names ungoverned WhatsApp use as the problem being solved, and §4.2 which defines Channels as governed role queues.
• No silent loss of work — messages that should become structured requests must not be allowed to disappear into chat history without a conversion path. Derived from Technical Spec §4.3 which states that Structured Internal Requests must create a linked thread and a governed task, and §13.2 rule 7.
• No documents as attachments — files and documents must never be sent as e-mail attachments or copied outside governed storage. All document sharing within Communication Hub is by secure reference only, consistent with Document Hub's design principle that nothing is emailed as an attachment and nothing is copied to an external system. Inferred from the Document Hub technical specification.
• Delegated identity always visible — where a guardian or authorised representative communicates on behalf of a dependant, the represented patient's identity is persistently surfaced in the thread so that all participants and audit records unambiguously identify the subject. Inferred from Family Profiles governance requirements.

3. Design Philosophy

The Communication Hub embodies a single mental model: chat is the surface, but work is the system of record. The design treats familiar chat conventions as the entry point — message bubbles, reactions, @mentions — while layering operational governance on top without friction.

Empty states: A user who has no threads or channels sees prompt-driven onboarding pointing them to existing role-scoped channels rather than a blank screen, consistent with Technical Spec §4.2 which defines Channels as the correct governed alternative to ad-hoc group creation. (Exact onboarding copy needs UX writer input.)

Error states: Errors surface inline with a clear action the user can take. No error is left without a path forward. Inferred from Technical Spec §13.2 rule 11 — every UX interaction must map to a defined primitive; error paths must also resolve to a defined action rather than a dead end.

AI intent-detection suggestions: Suggestions from AI Assistant (Aiden) appear as inline, visually distinct prompts within the thread — not modal interruptions — consistent with Technical Spec §6.4 which defines the AIIntent suggestion payload and §7 which requires all AI suggestions to await explicit human approval before any action is taken. The user can convert or dismiss; dismissal is logged per Technical Spec §8.

Multi-step flows: Request conversion is a single-step inline action where the request type is unambiguous; complex or admin-defined request types may use a short, in-context wizard, inferred from Technical Spec §4.3 which allows admin-defined structured request types with configurable routing and SLAs. (Step count and labelling for wizards need UX writer input.)

Undo/redo: Chat messages may be edited or retracted according to the practice's retention policy. Request-linked messages are locked once a request has been created, consistent with Technical Spec §13.2 rule 7 which transfers execution ownership and retains no further editing lifecycle in Communication Hub. CallThread transcripts are permanently immutable once a call ends, per Technical Spec §3.1.1.

Read-only vs editable surfaces: Request-linked chat threads are read-only for the conversation record once converted; only the linked task object is editable through the appropriate workflow in Task Manager. Announcement posts are read-dominant with no open reply thread, per Technical Spec §3.3 rule: "Announcements do not allow replies." CallThread transcript panels are always read-only. Escalated Aftercare conversations are read-only for all roles except those explicitly authorised to act — see §5.4.

4. Primary Surfaces

4.1 Web Portal

Who uses it: Managers, practice owners, and administrators — roles with oversight responsibilities — inferred from Technical Spec §5.1 which grants the Web Portal full access to all primitives, and §9.1 which grants Approve/Promote permissions to Admin and Management roles.

Key tasks performed here:

• View, filter, and manage all conversation threads and channels the user's role has permission to access, inferred from Technical Spec §5.1 feature matrix.
• Create, schedule, and publish Announcements (including Critical-priority announcements), inferred from Technical Spec §3.3 and §9.1 Announcement permission row.
• Review the full acknowledgement completion status for any Announcement that requires acknowledgement, inferred from Technical Spec §3.4 which requires per-user acknowledgement tracking.
• Monitor SLA health across open and in-progress threads, inferred from Technical Spec §3.1 SLAState field and §13.3 per-object SLA overrides.
• Access audit surfaces — AI suggestions shown/dismissed, message-to-work conversion events, blocked group-chat attempts, SLA breaches, notification suppression and urgency-override decisions — inferred from Technical Spec §8 audit event list.
• Configure Communication Hub admin settings: structured request types, routing, SLAs; channel role assignments; announcement acknowledgement requirements; scheduled event types; notification suppression windows aligned to Rota Manager — inferred from Technical Spec §13.3 practice-level configuration surfaces.
• Manage ownership reassignment for threads where an owner's access has been revoked, inferred from Technical Spec §9.2 which states that affected threads must be flagged for manual reassignment by an admin.
• Review read-only escalated Aftercare conversation threads (authorised clinical roles only), with full AI interaction history and prior patient responses visible — see §5.4.

Layout pattern: List-detail with filtering and oversight panels — a left-hand list of threads/channels with a right-hand detail pane, plus a separate admin configuration area accessible from a top-level navigation item, inferred from the breadth of oversight tasks and the full feature matrix in Technical Spec §5.1.

4.2 Tablet App

Who uses it: Clinical and front-of-house staff working within the practice — the primary operational users of Communication Hub during a working day — inferred from Technical Spec §5.2 which grants the Staff App Mode full access to all primitives, and §1 which names staff communication as the module's primary remit.

Key tasks performed here:

• Send and receive direct chats (1:1) and participate in role-scoped channels, inferred from Technical Spec §5.2 feature matrix (Chats ✅, Channels ✅).
• View, acknowledge, and react to Announcements, inferred from Technical Spec §5.2 (Announcements ✅, Acknowledgements ✅).
• Submit Structured Internal Requests using guided submission flows, inferred from Technical Spec §5.2 (Structured Requests ✅) and §4.3.
• Send and receive Praise, inferred from Technical Spec §5.2 (Praise ✅).
• Use message-to-work conversion to create a callback, task, or approval, or to hand off to Appointment Manager, from any thread — inferred from Technical Spec §4.5 which applies to all chat and channel threads.
• View AI intent-detection suggestions inline and choose to convert or dismiss them, inferred from Technical Spec §6.4 and §7.

Touch ergonomics: All touch targets must be ≥44×44 px. Glove-friendly tap targets are preferable at ≥48 px where feasible. Primary actions must be reachable without two-handed grip wherever possible.

4.3 Mobile App (Patient or Staff)

Who uses it: Patients — this surface is constrained to patient-facing interactions only, inferred from Technical Spec §5.3 which restricts the Patient App to Chats (patient-facing only) and Acknowledgements (where relevant), and explicitly excludes Channels, Announcements, Praise, and Structured Requests.

Key tasks performed here:

• Initiate and participate in a direct conversation thread with the practice, inferred from Technical Spec §5.3 (Chats ✅ patient-facing only).
• Complete acknowledgements relevant to the patient's care journey — for example, confirming receipt of a document or responding to a consent-related acknowledgement — inferred from Technical Spec §5.3 (Acknowledgements ✅ where relevant) and §3.6.
• Receive proposal delivery from Smart Treatment Proposals via this surface, inferred from Technical Spec §6.1 integration row for Smart Treatment Proposals which names Patient Mobile App as the primary delivery channel.
• Submit questions about a Smart Treatment Proposal from within the proposal context; these questions are surfaced to staff as Q&A threads linked to the proposal (see §5.1 Flow 8 and §5.4).
• Initiate a question thread in response to a recall or reconnect outreach message; doing so advances the recall journey to the Engaged sub-state, halting further automated escalation (see §5.1 Flow 6 and §5.4).

Patient conversations must remain professional and policy-safe at all times; the social features available to internal staff (emoji reactions, GIFs, voice notes) are not available on this surface, inferred from Technical Spec §5.3 feature exclusions and the module's patient-facing governance requirements in §2.1.

4.4 Staff App Mode (Mobile)

Who uses it: Staff members accessing Communication Hub through the mobile Staff App Mode — typically when away from a tablet or workstation but within or near the practice. Inferred from Staff App Mode §4.3, which lists reading and sending secure messages, participating in group chats and channels, viewing announcements and praise, and submitting structured requests as key tasks on this surface.

Key tasks performed here:

• Read and send secure messages in direct chats and role-scoped channels.
• Participate in channels and view channel history.
• View announcements and submit acknowledgements.
• View and send Praise.
• Submit Structured Internal Requests using the same guided flows available on the Tablet App.
• View AI intent-detection suggestions and choose to convert or dismiss them.

This surface is subject to the same governance rules as the Tablet App: role-first ownership, no personal inboxes, no document attachments, and message-to-work conversion paths available from any thread. Touch ergonomics apply identically to §4.2. Features that are excluded from the Patient Mobile App (reactions, voice notes, GIFs for internal-only social cues) may be available here subject to the same open questions noted in §13.

5. Interaction Model

5.1 Primary Flows

Flow 1 — Unified chat space: entry and navigation

Inferred from Technical Spec §4.1 (Chat), §4.2 (Channel), and §3.2 state machine — every message belongs to exactly one thread, and there are no personal inboxes.

1. User opens Communication Hub.
2. A unified list displays Direct Chats and Channels relevant to the user's role. Each entry shows: thread name or participant name, context type (Direct / Channel / Patient / Lead / CallThread), role ownership badge, unread count, SLA risk indicator (where applicable), linked-work indicator (where applicable), and — where the thread originates from a recall/reconnect journey, a campaign, a Smart Treatment Proposal Q&A, a rewards outreach, an Aftercare escalation, an HR & People Manager workflow event, a Digital Forms assignment or reminder, or a Hygiene Subscriptions exception — a contextual origin badge.
3. User selects a thread or channel.
4. Thread view opens, displaying message history, current owner, thread status, and — where a request card is linked — the request card inline.
5. User composes a message. The system monitors input for intent signals in real time (see Flow 2).

CallThread entries (originating from AI Concierge calls) are visually distinguished in the unified list — see §5.4 for the CallThread surface pattern.

Flow 2 — AI intent detection and message-to-work conversion

Inferred from Technical Spec §4.5 (message-to-work conversion), §6.4 (Aiden intent suggestion payload), §7 (AI boundaries), and §13.2 rule 8 (all AI suggestions must be logged including accepted/rejected outcome).

1. User types a message in any direct chat or channel.
2. AI Assistant (Aiden) classifies intent asynchronously and, where confidence is sufficient, emits an AIIntent suggestion payload to Communication Hub.
3. Communication Hub surfaces an inline suggestion prompt within the thread, visually distinct from the message composer. (Exact prompt copy needs UX writer input — e.g. "This looks like a supply request. Log it formally?")
4. The prompt displays: detected intent type, confidence indicator, and two actions — Convert and Dismiss.
5. User selects Convert → a. If the request type is unambiguous, a request card is created inline. b. If the request type requires further detail (admin-defined structured request type), a short in-context guided form opens. c. A governed task is created in Task Manager. The task creation is an explicit, auditable action; the task inherits Task Manager's immutability and audit rules from the moment of creation. The thread carries a system marker confirming the task was created, who initiated the conversion, and the timestamp — this record is immutable in line with Task Manager's requirement that all state transitions be explicitly time-stamped and non-editable. d. The originating message remains visible and is linked to the request. e. A system marker appears in the thread. (Exact marker copy needs UX writer input — e.g. "Converted to Supply Request #1234.") f. SLA, ownership, and status become visible to all relevant participants via the request card. g. Where the detected intent implies a Treatment Pipeline action (e.g. marking a patient record as Lost or Closed), the conversion flow must surface an irreversibility warning before the Convert action is confirmed, consistent with Treatment Pipeline Manager's governance model for terminal stage transitions. The user must explicitly acknowledge the irreversibility of the action before the conversion proceeds. (Warning copy needs UX writer input.) h. Where the detected intent is campaign-related (e.g. "create a campaign for this audience segment"), the conversion prompt must offer a hand-off action to Campaign Manager rather than creating a generic task. A system marker is placed in the thread confirming the Campaign Manager hand-off, and Communication Hub emits the appropriate hand-off event. The thread remains open as a context reference. (Action label and system marker copy need UX writer input.)
6. User selects Dismiss → message is sent as-is; dismissal is logged in Audit & Compliance including IntentType, ConfidenceScore, and ThreadId.
7. Chat may continue for clarification, but the request is the system of record.

Flow 3 — Submitting a Structured Internal Request directly

Inferred from Technical Spec §4.3 which describes admin-defined guided submission flows for request types such as IT issues, supplies, and diary changes.

1. User selects New request from the channel or chat header actions.
2. User selects a request type from the admin-configured list. (Control label needs UX writer input.)
3. A guided form renders in-context with fields defined by the admin for that request type.
4. User submits the form.
5. A linked Conversation Thread is created.
6. A governed task is created in Task Manager. As with Flow 2, this task creation is an explicit, auditable event; the task's state transitions and governance actions are immutable per Task Manager's audit rules.
7. A request card appears in the thread confirming the request has been logged, with type, status, owner, and SLA.

Flow 4 — Creating and publishing an Announcement

Inferred from Technical Spec §3.3, §3.4, and §9.1 — Announcements are created by authorised admin/management roles, support scheduling and expiry, and require no reply thread.

1. Authorised user selects New announcement from the relevant section.
2. User completes: title, body, audience scope (Role / Site / Group), priority (Normal / Important / Critical), acknowledgement required (toggle), scheduled publish time (optional), expiry time (optional).
3. If priority is set to Critical, the system may apply an MFA gate enforced by Access Manager before the announcement can be published, per Technical Spec §9.2 final bullet. Whether MFA is required is an open question — see §13.
4. User reviews and confirms. (Confirmation modal copy needs UX writer input.)
5. Announcement is published or scheduled.
6. Recipients see the announcement as a read-dominant post. No reply thread is available. Reactions are available where enabled.
7. Where acknowledgement is required, each recipient sees a prominent acknowledgement action. Overdue acknowledgements may surface as tasks in Task Manager per Technical Spec §3.6 and §13.2 rule 9.

Flow 5 — Message-to-work: hand-off to Appointment Manager

Inferred from Technical Spec §4.5 which defines the hand-off payload and the full list of required fields.

1. From any thread, an authorised user selects Hand off to Appointment Manager from the message-to-work action menu.
2. The system presents a confirmation panel showing: patient/lead name, requested practitioner (pre-populated from thread context where available), appointment type (pre-populated where inferred), any time hint expressed in the thread, and the initiating role. Any scheduling constraints inferred from the thread context (e.g. practitioner availability, appointment type restrictions) are displayed at this point so that the user can review them before confirming — consistent with Appointment Manager's Find Next constraint-confirmation pattern. (Panel field labels and constraint display format need UX writer input.)
3. User confirms.
4. Communication Hub emits a hand-off event to Appointment Manager carrying the full booking-context payload (ThreadId, PatientId or LeadId, RequestedPractitioner, RequestedAppointmentType, RequestedTimeHint, InitiatedBy, Timestamp). This hand-off event is an explicit, auditable action and is immutable once emitted; it is logged to Audit & Compliance in the same manner as task-creation events.
5. A system marker appears in the thread confirming the hand-off. (Exact marker copy needs UX writer input.)
6. Communication Hub retains no further execution lifecycle. The thread remains open for context reference.

Flow 6 — Receiving and acting on an inbound patient reply (Recall & Reconnect)

Inferred from Technical Spec §6.1 integration row for Recall & Reconnect and §13.2 rule 13 — all inbound patient replies from recall/reconnect journeys must be surfaced as Conversation Threads owned by the appropriate role.

1. A patient replies to a recall or reconnect message, or submits a question in response to recall outreach (the "Ask a question" action in the patient-side recall journey).
2. Communication Hub receives the inbound reply event from Recall & Reconnect.
3. A Conversation Thread is created (or appended) and assigned to the appropriate owner role. Where the patient's action was "Ask a question", Communication Hub must notify Recall & Reconnect so that the recall journey can advance to the Engaged sub-state and automated escalation can be halted. This state handshake must be surfaced as a system marker in the thread so that staff can see that the recall journey is now paused pending their response. (System marker copy needs UX writer input.)
4. The thread appears in the owning role's channel/inbox list with an unread indicator and context badge indicating the recall/reconnect origin.
5. A staff member with the owner role opens the thread and responds or converts to work as appropriate. If the conversation resolves the patient's intent (e.g. they wish to book), the staff member may use the standard message-to-work hand-off (Flow 5) to progress to Appointment Manager.

Flow 7 — Giving Praise

Inferred from Technical Spec §3.5 — Praise is positive-only, non-anonymous, has no reply thread, and is visible to the configured audience.

1. Any staff member selects Give praise from the relevant surface.
2. User selects the recipient (a named user or role), enters a reason (free text), selects an optional category, and sets visibility (Team / Site / Organisation).
3. User confirms. (Confirmation copy needs UX writer input.)
4. Praise post is published to the selected audience as a read-dominant post. No reply thread. Reactions are available where enabled.
5. Praise is logged in the audit trail.

Flow 8 — Smart Treatment Proposal Q&A thread

Inferred from Smart Treatment Proposals technical spec §8.1 and §8.2, and STP UX §4.1 which lists "Review and respond to patient Q&A, including reviewing Aiden-suggested replies before sending" as a core task.

1. A patient submits a question about a Smart Treatment Proposal — either in-chair via staff-assisted input or through the Patient Mobile App.
2. Communication Hub receives the Q&A event from Smart Treatment Proposals and creates (or appends to) a Conversation Thread linked to the proposal context. The thread carries a proposal-origin badge so that staff can immediately identify the subject matter.
3. The thread appears in the owning role's list with an unread indicator. Staff open the thread and see the patient's question alongside any prior proposal context.
4. Where Aiden has suggested a reply, the suggestion appears as an inline intent-detection prompt within the composer — visually distinct from the staff member's own input — with the AI provenance indicator and a confidence signal. Staff MUST review and explicitly approve or dismiss the suggestion before any reply is sent. No AI-suggested reply is transmitted without an explicit human confirm action, consistent with Technical Spec §7.
5. Staff compose and send a reply (whether Aiden-assisted or self-authored). The sent reply is visible in the thread and is also surfaced back to Smart Treatment Proposals so that the proposal's Q&A state is updated.
6. If the patient's question implies a booking intent, a task, or any other actionable work, the standard message-to-work conversion path is available from this thread (Flow 2).

Flow 9 — Rewards Manager staff-led outreach

Inferred from Rewards Manager UX §4.1 and technical spec §5.3 and §11.2, which describe staff-led outreach for stalled referrals and unredeemed rewards as a task initiated via Communication Hub.

1. A staff member with appropriate permissions (typically a manager or front-of-house role) identifies a patient with a stalled referral or an unredeemed reward — either from within Rewards Manager or from a Communication Hub notification surfaced for this purpose.
2. The staff member selects Send outreach message from the relevant rewards or referral context. (Action label needs UX writer input.)
3. Communication Hub opens a new patient-facing Conversation Thread (or appends to an existing one) pre-populated with the rewards/referral context. The thread carries a rewards-origin badge.
4. The staff member reviews and customises the outreach message, then sends it.
5. The sent message is auditable and linked to the rewards/referral record. If the patient replies, the inbound message surfaces in the thread using the standard inbound reply flow. If the conversation leads to a booking or task, the standard message-to-work conversion path is available (Flow 2 or Flow 5).

Flow 10 — Subscription-related payment exception routing (Hygiene Subscriptions)

Inferred from Hygiene Subscriptions technical spec §6.3, which references Communication Hub as the delivery channel for payment exception notifications and subscription status events.

1. Hygiene Subscriptions emits a payment exception event (e.g. payment failure, subscription lapse, pending enrolment requiring action) to Communication Hub.
2. Communication Hub surfaces the event as an in-thread notification or in-app banner routed to the appropriate staff role. The notification carries a subscription-origin badge and clearly states the exception type and the patient or account it relates to.
3. Where the exception represents an action that staff must take (e.g. contacting the patient, escalating a payment failure), the message-to-work conversion path is available — the staff member may convert the notification to a governed task (Flow 2) or hand off to the appropriate workflow.
4. Patient-facing notifications (e.g. informing the patient of a payment failure) are routed through Communication Hub's standard patient thread; no module may contact the patient directly outside this channel.
5. All subscription exception events and any resulting conversions are logged to Audit & Compliance.

Flow 11 — HR & People Manager workflow notifications and escalations

Inferred from HR & People Manager governance requirements, which emit leave-acknowledgement events, workflow-step assignments, and escalation notifications that Communication Hub must broker.

1. HR & People Manager emits a governance event to Communication Hub — for example: a leave request requiring acknowledgement from the recipient, a workflow step assigned to a staff member's role, or an escalation triggered by an overdue HR action.
2. Communication Hub surfaces the event as an in-thread notification or in-app banner routed to the appropriate staff role. The notification carries an HR-origin badge and clearly states the event type, the staff member or role it concerns, and any action required.
3. Where the event requires an explicit acknowledgement (e.g. confirming receipt of a policy update or a workflow assignment), a prominent acknowledgement CTA is displayed on the notification. The acknowledgement is recorded and logged to Audit & Compliance; once completed, the CTA is replaced with a completion confirmation and Communication Hub notifies HR & People Manager of the acknowledgement outcome.
4. Where the event represents an action that must be converted to governed work (e.g. an overdue HR workflow step that requires a task to be raised), the standard message-to-work conversion path is available (Flow 2). A system marker is placed in the thread on conversion, and the resulting task in Task Manager is linked back to the originating HR event.
5. HR & People Manager workflow escalations that are routed to a manager role surface in that role's channel list with an unread indicator and the HR-origin badge. The manager may respond, convert to a task, or reassign ownership from within the thread.
6. All HR-originated events, acknowledgements, and conversion actions are logged to Audit & Compliance with actor attribution.

Flow 12 — Loyalty Insights outreach handoff

Inferred from Loyalty Insights §4.1, which references Communication Hub as the execution channel for loyalty-cohort-driven patient outreach (coordinated via Recall & Reconnect and Campaign Manager).

1. Loyalty Insights identifies a patient cohort requiring outreach and submits a structured handoff request to Communication Hub, specifying the cohort context, the outreach intent (e.g. re-engagement, reward reminder), and the preferred channel (direct message, campaign, or recall journey).
2. Communication Hub receives the handoff and routes it to the appropriate execution surface:
3. If the intent maps to a Recall & Reconnect journey, Communication Hub notifies Recall & Reconnect and surfaces the resulting thread using the standard recall reply flow (Flow 6) when the patient responds.
4. If the intent maps to a campaign, Communication Hub routes the request to Campaign Manager. Staff see the resulting outreach message in the relevant patient thread with a campaign-origin badge (see §10, Campaign Manager touchpoint).
5. If the intent maps to a direct staff-authored message, a new patient-facing Conversation Thread is created, pre-populated with the loyalty cohort context, and assigned to the appropriate owner role for review and send.
6. To prevent duplicate outreach, Communication Hub checks for an existing open thread with a loyalty, recall, or campaign origin for the same patient before creating a new thread. Where an existing thread is found, the new outreach context is appended rather than creating a parallel thread. (Exact deduplication logic and staff-facing indication need UX writer input.)
7. All loyalty-originated outreach events, thread creations, and conversion actions are logged to Audit & Compliance.

Flow 13 — Digital Forms assignment notifications and completion acknowledgements

Inferred from Digital Forms spec §5.2 and §13.2 rules, which describe form assignment, expiry, and mandatory-form blocking as events that may require notification and acknowledgement routing through Communication Hub.

1. Digital Forms emits a notification event to Communication Hub — for example: a form has been assigned to a patient or staff member, a form is approaching its expiry deadline, or a mandatory form is overdue and is blocking a workflow.
2. Communication Hub surfaces the event as an in-thread notification or in-app banner routed to the appropriate recipient. The notification carries a forms-origin badge and clearly states the form name, the deadline or expiry (if applicable), and any action required.
3. Where the event is addressed to a patient, it is routed to the patient's standard conversation thread. Where it is addressed to a staff role, it surfaces in the relevant channel or as an in-app banner, consistent with the urgency classification of the form event.
4. Form completion acknowledgements — confirming that a form has been submitted or that a mandatory-form block has been resolved — are surfaced as acknowledgement CTAs on the relevant notification. Once the form is completed, Communication Hub receives a completion event from Digital Forms, removes the CTA, and records the acknowledgement to Audit & Compliance.
5. Communication Hub does not duplicate notifications: if a form-assignment notification has already been surfaced and is open, a reminder event from Digital Forms results in a system marker appended to the existing notification thread rather than a new thread being created, to avoid parallel notification channels for the same form event. (Deduplication and reminder escalation logic need UX writer input.)
6. All form-assignment events, completion acknowledgements, and overdue escalations are logged to Audit & Compliance.

Flow 14 — AI Meeting Notes action-confirmation and meeting artefact sharing

Inferred from Technical Spec §6.1 AI Meeting Notes integration row and AI Meeting Notes specification.

1. AI Meeting Notes completes a meeting summary and emits a delivery event to Communication Hub, carrying the meeting artefact (summary, action list) and the target channel or thread.
2. Communication Hub posts the artefact as a system-initiated message into the specified channel or Conversation Thread. The post is visually distinguished as system-originated (system marker treatment with an AI Meeting Notes origin badge), so that participants can distinguish it from human-authored messages.
3. Where the meeting artefact includes assigned action items, each action item may be individually converted to a governed task via the standard message-to-work conversion path (Flow 2). The Convert action is available inline on each action-item entry within the posted artefact.
4. Where participants need to discuss, clarify, or acknowledge meeting outcomes, they do so via the standard thread reply model in the channel or thread into which the artefact was posted. Communication Hub does not create a separate reply thread for each artefact; all discussion is co-located with the original post.
5. If a participant believes an action item has been incorrectly attributed or requires reassignment, they may use the standard Structured Internal Request flow (Flow 3) to raise a formal reassignment request, linked to the meeting artefact thread for context.
6. All meeting artefact delivery events and any resulting task-conversion actions are logged to Audit & Compliance.

5.2 State Machines (Mirror of Technical Spec § 3)

Conversation Thread states

States and rules inferred directly from Technical Spec §3.2.

Rules: - Threads are never deleted; archival is the only terminal state, per Technical Spec §3.2. The archive action must be presented as irreversible and require explicit confirmation. - The current OwnerRole is always displayed within the thread header, per Technical Spec §3.1 OwnerRole field requirement. - On access revocation, thread ownership is transferred automatically or flagged for manual admin reassignment, per Technical Spec §9.2. The thread header must display a warning state where ownership has been flagged but not yet reassigned. (Warning copy needs UX writer input.)

Announcement states

States and rules inferred directly from Technical Spec §3.4.

• Where acknowledgement is required and a user has not acknowledged by the RequiredBy timestamp, the announcement entry in the user's list is flagged with an overdue indicator, inferred from Technical Spec §3.6 and §13.2 rule 9.
• Acknowledgement completion counts are visible to the creator/admin in real time on the published announcement, inferred from Technical Spec §3.4 rule: "Acknowledgements (where required) are tracked per user."

Acknowledgement states

Inferred from Technical Spec §3.6.

5.3 Empty / Loading / Error / Offline States

Every screen must define the following four states:

Unified chat list

• Empty state: A user whose role has no active threads or channels yet sees an onboarding prompt directing them to existing role-scoped channels and explaining how to start a direct chat. No blank screen. Inferred from Technical Spec §4.2 — Channels are the governed default for group communication. (Onboarding prompt copy needs UX writer input.)
• Loading state: Skeleton list rows maintain the visual shape of the unified chat list entries to prevent layout shift.
• Error state: An inline error message replaces the list with a retry action. Inferred from Technical Spec §13.2 rule 11 — every UX interaction must map to a defined primitive; dead ends are not permitted. (Error message copy needs UX writer input.)
• Offline state: The last-loaded thread list is shown in a read-only cached state with a prominent connectivity banner. New messages cannot be sent; the composer is disabled with an explanation. Inferred from Technical Spec §5's multi-surface delivery commitment and the governance requirement that no message is silently lost. (Offline banner copy needs UX writer input.)

Thread / channel view

• Empty state (new thread): A prompt indicating that the conversation is new and inviting the first message. For a patient thread, a policy-safe introductory note may be pre-populated. Inferred from Technical Spec §3.1 ContextType distinction between Internal and Patient threads. (Copy for both variants needs UX writer input.)
• Loading state: Skeleton message bubbles of varying widths render in chronological order to indicate content is loading.
• Error state: Inline error below the composer if a message fails to send, with a retry action. The failed message is held in the composer. (Error and retry copy needs UX writer input.)
• Offline state: Composer disabled; an inline banner explains that messages will send when connectivity is restored. Read access to cached message history is maintained.

Announcement list

• Empty state: A message indicating no active announcements for the user's role/site. Inferred from Technical Spec §3.3 AudienceScope — a user outside the scope of any published announcement sees nothing, which must be explained rather than left blank. (Copy needs UX writer input.)
• Loading state: Skeleton announcement cards.
• Error state: Inline error with retry. (Copy needs UX writer input.)
• Offline state: Cached announcements shown in read-only state. Acknowledgement actions are queued and submitted on reconnection, with a banner explaining the queued state.

Structured request submission flow

• Empty state (no request types configured): A message directing the user to contact their administrator, as request types are admin-configured per Technical Spec §13.3. (Copy needs UX writer input.)
• Loading state: Form skeleton with field outlines.
• Error state: Inline validation errors per field; submission-level error with retry. (Copy needs UX writer input.)
• Offline state: Submission blocked; inline explanation that the request will need to be submitted once connectivity is restored.

5.4 Specialist Surface Patterns

This section documents interaction patterns for thread types that carry additional constraints beyond the standard Conversation Thread model.

CallThread (AI Concierge call records)

CallThreads are a sub-type of Conversation Thread originating from AI Concierge calls, defined in Technical Spec §3.1.1. They are distinguished from standard threads in the following ways:

• Unified chat list: A CallThread entry carries a call-type indicator (e.g. a phone/call icon) and displays call metadata inline — mode (inbound/outbound), duration, and call end timestamp — so that staff can identify call records at a glance without opening them. (Exact icon and metadata layout need design-system confirmation — see §13.)
• Thread view: The thread view for a CallThread renders the immutable transcript panel (see Component Inventory §6) alongside any linked request cards or system markers. The composer is absent — CallThread records cannot be replied to; they are governance records only. Any follow-up action must be taken via a new linked thread or by converting a call-derived intent to a task using the standard message-to-work action menu.
• Detected intents list: Aiden-detected intents from the call are displayed as a read-only list within the transcript panel. Staff may act on a detected intent by selecting it and using the Convert action, which opens the standard request creation flow (Flow 2 step 5). This is the only interactive element within the transcript panel; all other content is permanently read-only.
• Takeover and handover events are shown as system markers within the transcript panel, consistent with the standard system marker treatment, and are logged to Audit & Compliance.

Escalated Aftercare conversations

When Aftercare Manager escalates a patient conversation to a human clinical role, Communication Hub surfaces that conversation as a read-only thread for all participants except the explicitly authorised clinical role. This pattern applies on both the Web Portal and Tablet App:

• The thread header carries an Aftercare-origin badge and displays the full AI interaction history and prior patient responses above any new human-authored content, so that the authorised clinician has complete context before responding.
• The thread is read-only for all roles without explicit authorisation. The read-only state is visually consistent with the standard read-only treatment (no composer, lock icon, explanatory label) but also includes a visible attribution of which AI interactions preceded the escalation and when the escalation was triggered.
• AI-authored or AI-suggested content within the thread is marked with the AI provenance indicator throughout, consistent with the governance-always-visible principle (§2). No AI-suggested reply may be transmitted without an explicit human confirm action.
• Authorised clinical roles may respond using the standard composer. Any response is logged as an explicit, auditable event to Audit & Compliance.

Family Profiles: delegated-identity rendering

Where a guardian or authorised representative communicates on behalf of a dependant via Communication Hub, the represented patient's identity MUST be persistently displayed throughout the thread to ensure unambiguous audit trails. Specifically:

• The thread header displays both the communicating party (guardian) and the represented patient (dependant), e.g. "Jane Smith (on behalf of Oliver Smith)". This rendering applies on all surfaces — Web Portal, Tablet App, Staff App Mode, and Patient Mobile App. (Exact label format needs UX writer input.)
• Consent confirmations, permission-change notifications, and invite-code delivery sent to guardian contact channels are surfaced as a distinct message type within the relevant thread, carrying a delegated-consent badge so that staff can distinguish them from standard messages.
• All messages in a delegated thread are attributed to the represented patient in Audit & Compliance, with the guardian's identity recorded as the communicating party. This dual attribution is not editable.
• If the guardian's delegated permissions are revoked or changed, a system marker appears in the relevant thread(s) noting the change. The thread's OwnerRole is notified. (System marker copy and notification routing need UX writer input.)

6. Component Inventory

New components introduced or extended by this module:

• Unified chat list — combined direct chats and channels list; each entry shows thread name, context type (Direct / Channel / Patient / Lead / CallThread), role ownership badge, linked-work indicator, SLA risk indicator, unread state, and — where applicable — a contextual origin badge (Recall & Reconnect, Campaign, Smart Treatment Proposal Q&A, Rewards outreach, Aftercare escalation, Hygiene Subscriptions exception, HR & People Manager workflow event, Digital Forms assignment, Loyalty Insights outreach). Present on Web Portal, Tablet App, and Staff App Mode. Inferred from Technical Spec §4.1, §4.2, and §5.1–5.2 feature matrices.
• Chat thread view (internal) — message bubbles, @mentions, reactions, and in-thread request cards. Tablet App, Staff App Mode, and Web Portal. Inferred from Technical Spec §4.1 and §4.2. (Internal-only social features such as voice notes, GIFs, and emoji are subject to confirmation — see §13.)
• Chat thread view (patient) — message bubbles, professional tone only; no reactions, GIFs, or voice notes. Patient Mobile App and Web Portal (staff side of patient thread). Inferred from Technical Spec §5.3 and §2.1.
• Request card (in-thread) — displays request type, current status, owner role, SLA state, and a link to the governing task in Task Manager. Appears inline when a formal request is linked to a thread. Inferred from Technical Spec §4.3 and §4.5.
• Intent-detection prompt — inline, visually distinct suggestion within the message composer; surfaces AI-detected intent with Convert and Dismiss actions. Never modal. Used for standard message-to-work intent, Aiden-suggested replies in Smart Treatment Proposal Q&A threads, AI Guardian alert content suggestions, and Aiden knowledge-base answers surfaced within staff chat (see §10, AI Assistant touchpoint). Inferred from Technical Spec §6.4 AIIntent payload contract and §7 AI boundaries.
• System marker — read-only, visually de-emphasised thread entry confirming a governance event (e.g. conversion, hand-off, archival, ownership transfer, recall journey state change, delegated-permission change, task creation, HR workflow acknowledgement, meeting artefact delivery, campaign hand-off). Inferred from Technical Spec §3.2 state machine audit requirement and §4.5 hand-off event.
• Announcement post — read-dominant, no open reply thread; displays priority badge, audience scope, expiry (if set), acknowledgement CTA (if required), and acknowledgement completion count (for authorised roles). Inferred from Technical Spec §3.3 and §3.4.
• Acknowledgement CTA — a prominent, single-action element on any object (announcement, document, task, HR workflow notification, Digital Forms assignment) that requires explicit acknowledgement. Removed on completion; replaced with a completion confirmation. Inferred from Technical Spec §3.6.
• Praise post — read-dominant; no reply thread; shows sender, recipient, reason, category (optional), and visibility scope. Reactions optional. Inferred from Technical Spec §3.5.
• Structured request submission form — guided, in-context form rendered from admin-configured request type definitions; used for both inline conversion and direct submission. Inferred from Technical Spec §4.3.
• CallThread transcript panel — read-only, immutable transcript view with call metadata (start time, end time, duration, mode), detected intents list (read-only, each intent selectable to trigger a Convert action), final outcome, and takeover event log. No composer is rendered within a CallThread view. Inferred from Technical Spec §3.1.1 CallThread sub-type fields and §5.4.
• Origin badge — a pill or tag component indicating the originating module or journey for a thread or notification (e.g. "Recall & Reconnect", "Smart Treatment Proposal", "Rewards", "Aftercare", "Campaign", "Hygiene Subscriptions", "HR & People Manager", "Digital Forms", "Loyalty Insights", "AI Meeting Notes"). Visually consistent across all thread types; provides context without replacing the thread type indicator.
• Delegated-identity header — a persistent header element within threads involving a guardian/representative, displaying both the communicating party and the represented patient. Always visible regardless of scroll position within the thread. Inferred from Family Profiles governance requirements and §5.4.
• Notification suppression indicator — a visible indicator in the user's profile or notification preferences area showing whether their notifications are currently in a rota-gated suppression window. Inferred from Technical Spec §6.5 rota-driven notification gating rules.
• Audit view panel (Web Portal) — tabular view of logged events filterable by event type, date range, actor, and thread. Inferred from Technical Spec §8 full audit event list and §5.1 Web Portal access scope.

Reused from the design system:

• Toast / in-app banner
• Form fields and validation patterns
• Wizard / multi-step form shell
• Data table (for audit view and acknowledgement completion tracking)
• Modal confirmation dialog (for irreversible actions — archival, hand-off confirmation, Treatment Pipeline terminal-stage conversion warnings)
• Skeleton loading states
• Badge / pill (for status, priority, and SLA indicators)
• Admin toggle controls

7. Visual Design Notes

• Typography: (needs UX writer input — pending design-system confirmation)
• Colour: SLA risk states use semantic warning and error colours. Request cards use a distinct bordered treatment to separate them from conversational message bubbles, inferred from the need to make governance visible per §2 and the request card component above. Critical announcements use the semantic error/critical colour. System markers are visually de-emphasised (muted text style) to avoid cluttering the thread. Origin badges use a consistent, low-contrast tint treatment that distinguishes module origin without competing with message content or status indicators. Read-only escalated Aftercare threads use a distinct visual treatment to prevent confusion with editable threads. Inferred from Technical Spec §3.3 Priority field (Normal / Important / Critical) and §3.4 announcement state machine. (Exact semantic colour tokens need design-system confirmation.)
• Iconography: An AI or "suggest" icon (distinct from standard action icons) is required for the intent-detection prompt component to make AI involvement immediately recognisable, inferred from Technical Spec §7 AI boundaries and §6.4. This same icon treatment is used for Aiden knowledge-base answers surfaced within staff chat threads, so that staff can immediately distinguish AI-sourced guidance from human-authored messages. A call/phone icon distinguishes CallThread entries in the unified list. A lock icon is used consistently for all read-only thread states. (Full icon set and sizing need design-system confirmation. Icon-only controls must always have a visible label or accessible tooltip.)
• Motion: Transition animations are appropriate for thread loading and message receipt. The intent-detection prompt should appear without sudden motion to avoid alarming the user mid-composition. Nothing in the call transcript panel should animate, as it is a governance record. Inferred from Technical Spec §3.1.1 immutability requirement for CallThread transcripts and the "calm by default" principle in §2. All motion must respect prefers-reduced-motion; where this preference is set, transitions are replaced by instant state changes.

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 (Windows), VoiceOver (iOS/macOS), and TalkBack (Android). (Confirm which platforms are in scope for MVP — see §13.)

Module-specific accessibility requirements:

• The intent-detection prompt must be announced to screen readers when it appears within the composer, without interrupting the user's current focus context. An ARIA live region with polite politeness level is appropriate. This applies equally when the prompt surfaces an Aiden-suggested reply in a Smart Treatment Proposal Q&A thread, an AI Guardian alert suggestion, or an Aiden knowledge-base answer within a staff chat thread. Inferred from the inline, non-modal requirement for the intent-detection prompt in §3 of this spec and Technical Spec §6.4.
• CallThread transcript panels must be fully keyboard-navigable and screen-reader-readable. The immutability of the transcript must be communicated semantically (e.g. aria-readonly, not just visually), inferred from Technical Spec §3.1.1. The detected-intents list within the transcript panel must also be keyboard-navigable, with the Convert action for each intent operable without a pointer device.
• Acknowledgement CTAs must be operable via keyboard and must communicate their state (pending / completed / overdue) programmatically, not only through colour or position, inferred from Technical Spec §3.6 and the governance requirement that acknowledgements are explicit decision events. This applies equally to acknowledgement CTAs on HR & People Manager workflow notifications and Digital Forms assignment notifications.
• Notification suppression states must be communicated to screen readers so that staff with visual impairments are aware when notifications are being gated, inferred from Technical Spec §6.5.
• The delegated-identity header within guardian/representative threads must be announced to screen readers when a thread is opened, so that staff are immediately aware of the represented patient's identity before reading or composing messages.
• Origin badges (Recall & Reconnect, Aftercare, Smart Treatment Proposal, HR & People Manager, Digital Forms, Loyalty Insights, AI Meeting Notes, etc.) must have accessible text equivalents; badge-only labelling without a programmatic text alternative is not permitted.
• Irreversibility warning modals (e.g. for Treatment Pipeline terminal-stage conversions and thread archival) must be fully keyboard-navigable and must communicate the irreversible nature of the action programmatically, not only through visual design.

9. Internationalisation

• Locale-aware date/time/number formatting. This is particularly relevant for CallThread metadata (call start/end times, duration) and Announcement scheduled/expiry timestamps, inferred from Technical Spec §3.1.1 and §3.3.
• All user-facing strings externalised. This includes admin-configured request type names and routing labels, which are user-visible strings and must therefore be stored in a way that supports externalisation, inferred from Technical Spec §13.3. It also includes origin badge labels, delegated-identity header formats, HR workflow notification labels, Digital Forms assignment notification labels, and Loyalty Insights outreach context labels, which are user-visible strings introduced in this version of the spec.
• Layouts tolerant of 30% string-length growth (German, French).
• RTL support: (to be confirmed — see §13)

10. Cross-Module UX Touchpoints

Where this module's UX intersects with related modules:

• Task Manager — when a chat message is converted to a formal request, or when a Structured Internal Request is submitted, a governed task is automatically created in Task Manager. The in-thread request card links directly to the task in Task Manager. The user can navigate to the task from the card without losing their place in the thread. Ownership, status, and SLA from Task Manager are reflected back into the request card in real time. All task-creation events and subsequent state transitions are immutable and explicitly time-stamped; Communication Hub's system markers reflect this immutability by being non-editable once placed. Inferred from Technical Spec §4.3, §4.5, §6.2, and Task Manager §2.
• Appointment Manager — the message-to-work hand-off flow (Flow 5 in §5.1) transitions the user's intent to Appointment Manager. Communication Hub surfaces a confirmation panel showing the booking context — including any inferred scheduling constraints — before emitting the hand-off event, consistent with Appointment Manager's Find Next constraint-confirmation pattern. After hand-off, Communication Hub retains no execution lifecycle; the thread remains as a context reference. Inferred from Technical Spec §4.5, §6.2, and Appointment Manager UX §4.1.
• AI Assistant (Aiden) — Aiden's intent suggestions appear inline within Communication Hub threads as intent-detection prompts (the AI inbox prompt component). Communication Hub never surfaces Aiden's internal classification logic; it only presents the suggestion and the Convert/Dismiss choice. In addition to message-to-work intent suggestions, Aiden may surface answers to internal staff Q&A questions drawn from the practice-approved knowledge base. These knowledge-base answers are visually distinguished from staff-authored messages by the AI provenance indicator and a visible label identifying the source as Aiden's knowledge base, so that staff immediately understand they are reading AI-sourced guidance rather than a colleague's response. As with all other Aiden suggestions, knowledge-base answers require no mandatory action from the recipient — the staff member may act on, dismiss, or simply read the answer — but the AI provenance must remain visible throughout the thread. All knowledge-base answer events are logged to Audit & Compliance. Inferred from Technical Spec §6.4, §7, and AI Assistant (Aiden) §5.1 and §6.1.
• Document Hub — when a document is dispatched to a staff member or patient, Communication Hub surfaces a delivery notification within the relevant thread or as an in-app notification. The document itself is stored in and governed by Document Hub. Documents must never be sent as attachments within Communication Hub messages or emails; all document sharing is by secure reference only, consistent with Document Hub's attachment-prohibition principle. Inferred from Technical Spec §6.2 outbound to Document Hub, §2.2 non-responsibility for document storage, and Document Hub design philosophy.
• Access Manager — the current user's role and active permissions are enforced by Access Manager and reflected in which primitives and actions are visible within Communication Hub. When a user's access is revoked, their thread ownership is automatically transferred or flagged; the affected thread displays an ownership warning state. MFA gates (e.g. for Critical Announcements) are enforced by Access Manager at the point of the confirm action. Inferred from Technical Spec §9.
• Audit & Compliance — governance events visible in the Web Portal audit view are sourced from the immutable Audit & Compliance log. Users with appropriate permissions can navigate from a thread event to its audit record. All communication events — message creation, modification, conversion, AI-assisted message generation, HR workflow acknowledgements, Digital Forms completion events, and Loyalty Insights outreach actions — are logged to Audit & Compliance with full actor attribution, including actor_type to distinguish human-authored actions from system- or AI-initiated ones, consistent with Security and Privacy audit trail requirements. Sensitive artefacts stored within Communication Hub (messages, structured requests, delegated-identity records) are subject to the platform's data retention policy; the UI must surface retention-limit warnings or archival prompts where the retention policy specifies a maximum age, as an open question noted in §13. Inferred from Technical Spec §6.2 outbound to Audit & Compliance, §8, and Security and Privacy governance framework.
• Campaign Manager — campaign step delivery requests are routed through Communication Hub. Staff with oversight permissions may see campaign-originated messages in the relevant patient thread, distinguished by a campaign origin badge. Where Aiden detects a campaign-related intent within a staff thread (e.g. a message expressing intent to create or send a campaign), the conversion prompt offers a dedicated Hand off to Campaign Manager action alongside the standard task-creation path, consistent with the hand-off pattern used for Appointment Manager (Flow 5). Communication Hub emits the appropriate hand-off event to Campaign Manager and places a system marker in the thread confirming the hand-off; it retains no further execution lifecycle for the campaign. Campaign Manager has no direct delivery surface of its own. Inferred from Technical Spec §6.1, §13.2 rule 12, and Campaign Manager UX.
• Recall & Reconnect — inbound patient replies from recall and reconnect journeys surface as Conversation Threads in Communication Hub, assigned to the appropriate owner role. A patient's "Ask a question" action advances the recall journey to the Engaged sub-state; Communication Hub notifies Recall & Reconnect of this state change and places a system marker in the thread to make the journey-state transition visible to staff. The thread entry includes a badge indicating the recall/reconnect origin so staff can contextualise the reply. Inferred from Technical Spec §6.1, §13.2 rule 13, and Recall & Reconnect §4.3.
• Referral Manager — patient milestone communication events triggered by referral state changes are delivered via Communication Hub. Staff see these as system-initiated messages within the relevant patient thread. Inferred from Technical Spec §6.1 integration row for Referral Manager.
• AI Guardian — alerts and summaries from AI Guardian are routed to the appropriate role via Communication Hub and surface as in-app notifications or thread entries depending on the event type. Where AI Guardian suggests alert content for human review before surfacing, the suggestion is presented as an intent-detection prompt with the standard Convert/Dismiss pattern; no AI-suggested alert content is committed to a thread without explicit human approval. Inferred from Technical Spec §6.1 integration row for AI Guardian and AI Guardian technical spec §7.
• Smart Treatment Proposals — proposal delivery to patients is routed through Communication Hub via the Patient Mobile App, with email and SMS as fallback channels. Patient Q&A threads linked to proposals are surfaced to staff in the unified chat list with a proposal-origin badge; Aiden-suggested replies within those threads require explicit staff approval before sending (Flow 8). From the staff side, the delivery event is visible in the relevant patient thread. Inferred from Technical Spec §6.1 integration row for Smart Treatment Proposals, STP technical spec §8.1–§8.2, and STP UX §4.1.
• AI Meeting Notes — meeting summaries and action lists from AI Meeting Notes are posted into a Conversation Thread or Channel as system-originated items (system marker treatment with an AI Meeting Notes origin badge), distinguishable from human-authored channel messages by both the origin badge and the AI provenance indicator. Individual action items within the posted artefact may be converted to governed tasks via the standard message-to-work path (Flow 14). The exact visual treatment that distinguishes a meeting artefact post from a standard system marker is an open question — see §13. Inferred from Technical Spec §6.1 integration row for AI Meeting Notes.
• Rota Manager — the notification suppression indicator reflects rota-driven gating data from Rota Manager. When a staff member is outside their shift hours, the suppression indicator is active. Urgent messages always override this gating and are always delivered. Inferred from Technical Spec §6.5.
• Product Shop — order confirmation, payment receipt, shipment, refund, and delivery issue notifications from Product Shop are routed through Communication Hub for delivery to staff and patients. Delivery issue notifications may be treated as urgent depending on urgency classification rules — this is an open question (see §13). Inferred from Technical Spec §6.1 integration row for Product Shop.
• Hygiene Subscriptions — payment exception notifications and subscription status events from Hygiene Subscriptions are routed through Communication Hub (Flow 10). Staff receive these as in-thread notifications or in-app banners with a subscription-origin badge; message-to-work conversion is available for exceptions that require follow-up action. Patient-facing subscription notifications are delivered via Communication Hub's standard patient thread. Inferred from Hygiene Subscriptions technical spec §6.3.
• Rewards Manager — staff-led outreach for stalled referrals and unredeemed rewards is initiated via Communication Hub (Flow 9). The resulting patient-facing threads carry a rewards-origin badge and are governed by the standard patient thread rules. Inferred from Rewards Manager UX §4.1 and technical spec §5.3 and §11.2.
• AI Concierge — call records from AI Concierge surface in Communication Hub as CallThread entries in the unified chat list, distinguishable by a call-type indicator and inline call metadata. Staff may access the immutable transcript and act on Aiden-detected call intents via the standard Convert action within the transcript panel. See §5.4 for the full CallThread surface pattern. Inferred from Technical Spec §3.1.1 and AI Concierge technical spec.
• Aftercare Manager — escalated patient conversations from Aftercare Manager surface in Communication Hub as read-only threads for all roles except the explicitly authorised clinical role, with full AI interaction history and prior patient responses visible. See §5.4 for the full escalated Aftercare conversation pattern. Inferred from Aftercare Manager UX §4.1 and §3.
• Family Profiles — guardian/representative communications on behalf of dependants are rendered with persistent delegated-identity headers in all thread views. Consent confirmations, permission-change notifications, and invite-code messages carry a delegated-consent badge. All messages are attributed to the represented patient in Audit & Compliance with the guardian recorded as the communicating party. See §5.4 for the full delegated-identity rendering pattern. Inferred from Family Profiles governance requirements.
• HR & People Manager — HR workflow notifications, leave-acknowledgement events, and escalations are routed through Communication Hub (Flow 11) and surface as in-thread notifications or in-app banners with an HR-origin badge. Acknowledgement CTAs on HR notifications follow the same governed pattern as Announcement acknowledgements; completions are reported back to HR & People Manager. Where HR events require conversion to governed work, the standard message-to-work path is available. Inferred from HR & People Manager governance requirements.
• Loyalty Insights — loyalty-cohort-driven outreach handoff requests from Loyalty Insights are received by Communication Hub and routed to the appropriate execution surface (Recall & Reconnect journey, Campaign Manager, or direct staff-authored message thread) via Flow 12. Deduplication of outreach threads for the same patient is enforced to prevent parallel notification channels. Inferred from Loyalty Insights §4.1.
• Digital Forms — form-assignment notifications, expiry reminders, and mandatory-form overdue alerts are routed through Communication Hub (Flow 13) with a forms-origin badge. Form completion events from Digital Forms remove the associated acknowledgement CTA and record the completion in Audit & Compliance. Communication Hub enforces deduplication so that reminders for an already-open form notification append to the existing thread rather than creating a parallel channel. Inferred from Digital Forms §5.2 and §13.2 rules.
• Admin Control Plane (ACP) — ACP staff (Support Engineers, Customer Success Managers, and Sales roles) who access the platform in Support Mode interact with Communication Hub's internal primitives under the constraints of their just-in-time support session. Within a support session, ACP staff may read thread content and governance records to which their support role has been granted access, but they may not author messages into patient-facing threads or override governed channel ownership. Support-mode access sessions are logged to Audit & Compliance with ACP actor attribution, consistent with the platform's audit trail requirements. Any escalation request that a support session generates (e.g. a request to reassign thread ownership on behalf of a practice) must be submitted as a Structured Internal Request (Flow 3) so that it is traceable. ACP staff do not have a dedicated Communication Hub surface; they operate within the existing Web Portal under their support-session permissions. Inferred from Admin Control Plane §4.10 and Communication Hub Technical Spec §4.3 and §5.2.
• Knowledge, Training & Learning — Communication Hub is the correct channel for learners or staff who have questions about learning content or course assignments that fall outside the scope of what the Knowledge module self-serves. The Knowledge module does not own a messaging or escalation surface; when a staff member needs to ask a question about a training requirement or course content that they cannot resolve within the Knowledge module, they do so via a direct chat or appropriate role-scoped channel in Communication Hub. Communication Hub does not create a dedicated knowledge-support thread type; these questions are handled as standard internal direct chats or channel messages and may be converted to Structured Internal Requests if they represent a formal support need. This boundary is intentional: the Knowledge module is not responsible for responding to individual questions, and Communication Hub must not create implicit notification coupling with Knowledge module events. Inferred from Knowledge, Training & Learning UX §2 (module does not remind or enforce) and Communication Hub's role as the platform's unified messaging broker.
• Treatment Pipeline Manager — when a message-to-work conversion (Flow 2) involves a Treatment Pipeline action — particularly any action that would trigger a terminal or irreversible stage transition (e.g. marking a record as Lost or Closed) — the conversion flow must surface an explicit irreversibility warning before the Convert action is confirmed, consistent with Treatment Pipeline Manager's governance model for protected stage transitions. The user must explicitly acknowledge the irreversible nature of the action; the warning must be presented as a confirmation modal (not an inline prompt) to ensure it cannot be accidentally dismissed. The task created in Task Manager upon confirmation inherits the same immutability and audit rules as all other converted tasks. Inferred from Treatment Pipeline Manager UX §2 Principle 7 and §3.

UX consistency rules:

• Intent-detection prompts are always inline within the composer, never modal. Inferred from Technical Spec §7 AI boundaries and the "calm by default" principle.
• System markers (conversion confirmations, hand-off events, ownership transfers, recall journey state changes, delegated-permission changes, task creation events, HR workflow acknowledgements, meeting artefact deliveries, campaign hand-offs, Digital Forms completion events) use a consistent visually de-emphasised style across all thread types so they are recognisable as governance events rather than user messages. Inferred from Technical Spec §8 audit event list and §3.2 state machine.
• Emoji, GIFs, and voice notes must never serve as the sole mechanism for acknowledgement, approval, or compliance in any surface or configuration. Inferred from Technical Spec §13.2 rule 8 and the overall governance posture.
• The Archived state is the only terminal state for all primitives; no delete action ever appears in the UI for any communication primitive. Inferred from Technical Spec §3.2 and §9.1.
• Reactions on Announcement and Praise posts never replace formal acknowledgements; the acknowledgement CTA must remain visible and distinct from the reactions area. Inferred from Technical Spec §3.4 and §3.5.
• Documents must never be shared as attachments within any Communication Hub message, email, or notification surface. All document references must be secure links to Document Hub. This constraint is non-configurable and must not appear as an admin toggle. Inferred from Document Hub design philosophy.
• AI-suggested content in any thread type (standard conversion suggestions, Smart Treatment Proposal Q&A replies, AI Guardian alert content, Aiden knowledge-base answers) must follow the same human-first approval or acknowledgement pattern: displayed as an intent-detection prompt with explicit AI provenance marking, requiring explicit Convert, Dismiss, or acknowledgement before any action is taken or content is committed to a thread. Inferred from Technical Spec §7.
• Irreversibility warnings for Treatment Pipeline terminal-stage conversions must use the confirmation modal pattern, not the inline intent-detection prompt pattern, to prevent accidental dismissal of a destructive action.

11. Governance & Auditability

How the UI surfaces governance:

• AI intent-detection suggestions are visually distinct from user messages — they appear as a styled inline prompt with an AI indicator icon, separate from the message composer and from sent messages. This applies across all thread types where Aiden may suggest content, including Smart Treatment Proposal Q&A threads, AI Guardian alert routing, and Aiden knowledge-base answers surfaced within staff chat threads. Inferred from Technical Spec §6.4 and §7.
• Every AI suggestion includes a visible confidence signal presented in a human-readable form (not a raw decimal), so that staff understand the system's certainty before deciding whether to convert. Inferred from Technical Spec §6.4 ConfidenceScore field.
• Audit-significant actions — request conversion, conversion prompt dismissal, blocked group-chat creation attempts, Announcement publishing, Acknowledgement completion, message-to-work hand-off events, CallThread takeover and handover events, notification suppression and urgency-override decisions, recall journey state changes triggered by patient messages, task creation via message conversion, delegated-permission changes, HR workflow acknowledgements, Digital Forms completion events, Loyalty Insights outreach thread creation, campaign hand-offs, Treatment Pipeline irreversibility confirmations, meeting artefact deliveries, ACP support-session access events — each trigger a system marker in the relevant thread and are logged to the Audit & Compliance module. Inferred from Technical Spec §8.
• All audit log entries include actor_type attribution to distinguish human-initiated actions from system- or AI-initiated ones, consistent with Security and Privacy audit trail requirements. AI-assisted message generation events are logged with the AI actor identified, so that any AI contribution to a sent message is traceable in the audit record.
• The Web Portal audit view presents these logged events in a filterable, exportable table. Inferred from Technical Spec §8 which states audit logs must be exportable for inspection.
• The current OwnerRole for every thread is permanently visible in the thread header. When ownership is in a flagged/unassigned state following access revocation, a warning indicator is displayed. Inferred from Technical Spec §3.1 OwnerRole field and §9.2.
• Read-only states — archived threads, resolved threads, request-linked conversation records, CallThread transcripts, escalated Aftercare threads (for non-authorised roles) — are visually distinct from editable surfaces. A consistent read-only treatment (e.g. no composer, lock icon, explanatory label) applies. (Exact treatment and label copy needs UX writer input.) Inferred from Technical Spec §3.1.1 transcript immutability, §3.2 archival terminal state, and Aftercare Manager §4.1.
• All system-initiated broadcast events (Scheduled Events, campaign deliveries, AI Guardian alerts, Hygiene Subscriptions exceptions, Rewards Manager outreach, HR & People Manager workflow notifications, Digital Forms assignment notifications, Loyalty Insights outreach) carry a "system-initiated" or module-origin badge so that staff can distinguish automated messages from human-authored ones. Inferred from Technical Spec §4.4 and §13.2 rule 10.
• Communication Hub surfaces no autonomous AI actions; every AI-suggested action requires an explicit human Convert or approve step before anything is committed. The UI must make this handover moment unambiguous. Inferred from Technical Spec §7 and §13.2 rule 8.
• Tasks created via message-to-work conversion are explicitly timestamped at the point of creation; the system marker placed in the thread at conversion time is non-editable and serves as the in-thread record of the auditable creation event, consistent with Task Manager's requirement that state transitions are immutable and explicitly time-stamped.
• Sensitive artefacts (messages, structured requests, delegated-identity records) are subject to the platform's data retention policy as defined by Security and Privacy. Where the retention policy specifies a maximum age, the UI must surface a retention-limit warning or archival prompt at the appropriate point in the thread or audit view lifecycle — this is an open question noted in §13.

The following are intentionally non-configurable by design, and must not appear as toggles in any admin surface:

• Emoji, GIFs, or voice notes as approval or acknowledgement mechanisms. Inferred from Technical Spec §13.2 and §7 AI boundary rules extended to all social primitives.
• Silent bypass of intent detection logging — every suggestion event must be logged regardless of outcome. Inferred from Technical Spec §8 and §6.4.
• Deletion of any conversation primitive — archival is the only terminal state. Inferred from Technical Spec §3.2 and §9.1.
• Autonomous AI action on any communication event. Inferred from Technical Spec §7.
• Document sharing as an attachment — all document sharing must be by secure reference via Document Hub. Inferred from Document Hub design philosophy.
• Suppression of actor_type attribution in audit log entries — all logged events must carry actor attribution distinguishing human from system or AI actors. Inferred from Security and Privacy audit trail requirements.

12. Notification & Communication Patterns

How this module requests user attention:

• In-app banner — used for urgent and critical events that require immediate awareness but do not require navigation: e.g. a Critical Announcement published to the user's role/site, an urgent message override during a suppression window, a connectivity loss (offline state banner), a Hygiene Subscriptions payment exception requiring immediate staff attention, or an HR & People Manager escalation requiring urgent action. Banners are persistent until the condition is resolved or acknowledged. Inferred from Technical Spec §3.3 Priority field (Critical) and §6.5 urgency override rule.
• Toast — used for low-urgency confirmations of completed actions: e.g. a request successfully converted, an Announcement successfully published, Praise successfully sent, an Acknowledgement recorded, a rewards outreach message sent, an HR workflow acknowledgement recorded, a Digital Forms completion event received, a meeting artefact successfully posted. Toasts are transient and auto-dismiss. Inferred from the range of user-initiated completion events across Technical Spec §4.1–§4.5. (Exact confirmation copy for each toast type needs UX writer input.)
• Push notification — staff push notifications are delivered via Communication Hub's own notification routing; consuming modules (Campaign Manager, Recall & Reconnect, Referral Manager, AI Guardian, Smart Treatment Proposals, Product Shop, Hygiene Subscriptions, Rewards Manager, HR & People Manager, Digital Forms, Loyalty Insights) must not send push notifications directly. Notification delivery for staff is gated by rota-driven shift data from Rota Manager: non-urgent notifications are suppressed outside shift hours; urgent or direct messages always override quiet hours and are delivered immediately. Inferred from Technical Spec §5, §6.1, §6.5, and §13.2 rule 16.
• Email and SMS — both channels are routed via Communication Hub. No module may deliver email or SMS directly to a patient or staff member; all such requests must be submitted to Communication Hub for execution and audit. Inferred from Technical Spec §2.1 and §13.2 rule 12.
• In-list unread indicators — channel and direct-chat unread counts are surfaced in the unified chat list without requiring a separate notification surface. These are the primary attention-directing mechanism for normal operational traffic. Inferred from Technical Spec §4.1 and §4.2.
• Overdue acknowledgement indicator — a persistent flag on the relevant announcement, HR workflow notification, Digital Forms assignment, or task entry that an acknowledgement is overdue. This may also generate a task in Task Manager. Inferred from Technical Spec §3.6 and §13.2 rule 9.

13. Open Questions

UX decisions to resolve before this spec is promoted from draft to published.

1. Which specific roles are permitted to create Announcements vs. Praise vs. Structured Requests? This directly affects which action controls are visible to which users. Awaiting Access Manager role definitions — Technical Spec §9.3 and §15 Q1.
2. Is MFA required for any specific communication operation — e.g. publishing a Critical Announcement? This determines whether a step-up authentication UI must be designed into the announcement publishing flow. Technical Spec §9.2 and §15 Q3.
3. Are reactions on Announcements and Praise enabled at MVP, or deferred? This determines whether the reactions component is in or out of scope for this build tier. Technical Spec §15 Q5.
4. What is the fallback ownership role when a thread owner's access is revoked and no explicit fallback is configured in Access Manager? The thread ownership warning state (§5.2) must know how to resolve — either automatically or via admin action. Technical Spec §15 Q6.
5. Should Campaign Manager delivery requests be presented to staff as a distinct visual primitive (e.g. a campaign badge/thread type) or wrapped in an existing Announcement or Chat treatment? This affects the component inventory. Technical Spec §15 Q7.
6. What urgency classification rules apply to Product Shop fulfilment events — specifically, are delivery issue notifications treated as urgent and therefore immune to rota-driven suppression? This affects the notification routing logic visible in §12. Technical Spec §15 Q8.
7. What is the data retention policy for conversation history, CallThread transcripts, and patient-bound message data? This affects whether and how the UI surfaces retention limits, archival prompts, or data expiry warnings, consistent with Security and Privacy requirements. Technical Spec §15 Q11.
8. Which screen readers are in scope for testing at MVP — NVDA, VoiceOver, and TalkBack, or a subset? (Carried from existing partial spec §13.)
9. Is RTL support required at MVP tier? (Carried from existing partial spec §13.)
10. What are the loading, error, and offline states for the Structured Request submission flow when Aiden's intent classification service is unavailable? Should the intent-detection prompt be suppressed, or should a degraded mode be shown?
11. Which lifecycle stages and complete state-machine UX definitions are needed for Patient Conversation Threads specifically — particularly the SLA policy and who configures it? Technical Spec §15 Q4.
12. (needs UX writer input — e.g. exact microcopy for all system markers, inline guidance strings, toast confirmations, error messages, the group-chat redirect explanation, the recall journey state-change system marker, the delegated-identity header format, HR workflow notification labels, Digital Forms assignment notification labels, Loyalty Insights outreach deduplication indication, campaign hand-off system marker, and Treatment Pipeline irreversibility warning modal copy — these strings are externalised per §9 but have not yet been authored)
13. What visual treatment distinguishes a CallThread from a standard Conversation Thread in the unified chat list? CallThreads carry additional metadata (call mode, duration, transcript) and must be recognisable at a glance. A call-type icon and inline metadata display is proposed in §5.4, but exact icon selection and metadata layout need design-system confirmation.
14. How are AI Meeting Notes postings distinguished from human-authored channel messages in the thread view? The system marker pattern with an AI Meeting Notes origin badge is proposed in §5.1 Flow 14 and §10, but the specific visual treatment relative to other system markers is not yet defined. Technical Spec §6.1 AI Meeting Notes integration row.
15. What is the staff-facing UI treatment for AI Guardian alert-content suggestions that are routed to Communication Hub for human review? The intent-detection prompt pattern is proposed in §5.1 and §10, but the specific alert context (e.g. how much of the Guardian's analysis is surfaced alongside the suggestion) needs confirmation from the AI Guardian UX specification.
16. Are social features (emoji reactions, voice notes, GIFs) available on Staff App Mode at MVP, or deferred? The Tablet App open question (§13 item 3 above) applies equally to Staff App Mode; this should be resolved as a single decision covering both surfaces.
17. What happens to an open Smart Treatment Proposal Q&A thread if the proposal is withdrawn or expired? Does the thread become read-only automatically, and if so, what system marker is placed and who is notified?
18. Is there a maximum thread age or message count after which Hygiene Subscriptions exception threads are auto-archived, and should the UI surface a warning before auto-archival occurs?
19. What is the exact deduplication logic for Loyalty Insights outreach threads — specifically, how does Communication Hub determine whether an existing open thread for a patient is sufficiently related to a new outreach context to warrant appending rather than creating a new thread? And how is this deduplication decision surfaced to staff? (Flow 12.)
20. What is the urgency classification for HR & People Manager escalation notifications — specifically, are overdue HR workflow escalations treated as urgent (immune to rota-driven suppression) or non-urgent? This affects notification routing logic in §12.
21. What is the staff-facing presentation of Aiden knowledge-base answers — specifically, is the full knowledge-base source reference surfaced to the staff member alongside the answer, and if so, in what format? This affects the intent-detection prompt component design for knowledge-base answer events. (§10, AI Assistant touchpoint.)
22. What permissions do ACP staff in Support Mode have within Communication Hub — specifically, can they read all thread content within a support session scope, or only governance metadata? This affects what is rendered in the Web Portal under a support-session access grant. (§10, Admin Control Plane touchpoint.)