Smart Treatment Proposals

Editing technical v0.2 — draft 📝 1 past meeting

Tab to switch the tab. Save writes a vNEW-DRAFT.md alongside the published file.

Markdown source

# Smart Treatment Proposals – Technical Specification
- Digital Treatment Proposals Module – Technical Specification (Primoro v4.4 Update 2) v1.0
- Modules‑Smart Treatment Proposals v1.0 (designer module spec)

## 1. Module Purpose & Scope (Authoritative)

Smart Treatment Proposals is Primoro's treatment conversion module — converting treatment recommendations into clear, patient‑understood, formally accepted treatment inside Primoro's secure ecosystem (not PDFs as the primary workflow).

It governs:

- creation and presentation of interactive, patient‑friendly proposals
- a two‑step explanation/acceptance model
- patient engagement tracking, Q&A, and conversion traceability
- auditable evidence of explanation, acknowledgement, and acceptance

It explicitly does not:

- perform diagnosis or clinical charting (owned by the PMS)
- replace statutory/clinical consent forms where separately required
- act as a messaging platform (Communication Hub owns delivery and timelines)
- execute marketing or recall programmes (Campaign Manager / Recall & Reconnect own those)
- manage appointment diaries (Appointment Manager owns booking and diary constraints)

## 2. Ownership & Responsibilities

### 2.1 Smart Treatment Proposals IS Responsible For

- Creating and maintaining proposal records linked to a patient and (where applicable) a Treatment Pipeline Opportunity.
- Presenting treatment options, phases, multimedia explanations, and payment routes in patient‑friendly language.
- Capturing the two‑step model:
- Step 1: acknowledgement that the plan was explained
- Step 2: acceptance to proceed and authorisation to book treatment
- Supporting patient questions (text and voice), call‑back requests, and proposal‑linked communication.
- Providing staff visibility of proposal engagement and state transitions.
- Maintaining an immutable audit trail of views, acknowledgements, acceptance/decline, signatures, and finance/payment interactions.

### 2.2 Smart Treatment Proposals IS NOT Responsible For

- Clinical diagnosis or definitive clinical treatment decisions.
- Booking appointments or determining diary availability (Appointment Manager owns this).
- Executing finance agreements (the module initiates applications and captures choices only).
- Sending outbound messages directly (all delivery flows through Communication Hub).
- Ingesting or transferring proposal artefacts into Document Hub. Smart Treatment Proposals retains and governs its own document artefacts within its own secure storage boundary; those artefacts are NOT ingested into Document Hub. Document Hub and Smart Treatment Proposals maintain a hard storage boundary: each module is the sole custodian of its own governed artefacts.

## 3. Core Objects (Normative)

### 3.1 Proposal (Canonical Artefact)

A Proposal is a governed digital artefact representing one or more treatment options presented to a patient.

Minimum required fields:

- ProposalID
- PatientID
- LinkedOpportunityID (nullable; required when associated to an Opportunity)
- ProposalState
- CreatedBy (user/role)
- PresentedVia (Tablet App / Patient App / Web Link)
- TreatmentOptions (one or more)
- PaymentProfileID (nullable)
- FinanceOptions (zero or more)
- AuditTrail (immutable)

Proposals are stored and retained inside Primoro's secure ecosystem and are inspection‑ready.

### 3.2 Proposal State Machine (Authoritative)

States:

- Draft (internal)
- Presented
- Explained & Acknowledged (Step 1 complete)
- Accepted (Step 2 complete)
- Declined
- Expired

Rules:

- State transitions are auditable and time‑stamped.
- Finance application initiation MUST NOT move a proposal to Accepted.
- Selecting a payment option MUST NOT move a proposal to Accepted.

#### Outbound Event Contract — ProposalAccepted

When a Proposal transitions to the Accepted state, the system MUST emit a `ProposalAccepted` event. This event MUST carry:

- `ProposalID`
- `LinkedOpportunityID` (where present)
- `PatientID`
- `AcceptedAt` (ISO 8601 timestamp)
- `SelectedPaymentProfileID` (where applicable)

Treatment Pipeline Manager MUST handle this event to advance the linked Opportunity's stage and unlock booking eligibility (see §9.1). No other module may alter Treatment Pipeline state as a result of a proposal transition; the event contract is the sole mechanism.

Additionally, the following outbound events MUST be emitted and made available to consuming modules (see §9 for per‑module detail):

- `ProposalCreated` — emitted when a Proposal is first saved (including Draft state).
- `ProposalPresented` — emitted when a Proposal transitions to Presented.
- `ProposalDeclined` — emitted when a Proposal is Declined.
- `ProposalStalled` — emitted when a Proposal has been Presented but has not progressed within a configurable period (system‑generated).
- `ProposalAccepted` — as defined above.

All emitted events are read‑only signals; consuming modules MUST NOT write back to proposal state via these events.

## 4. Proposal Creation & Content (Build‑Contract)

### 4.1 Treatment Outline & Options

Proposals MUST support:

- structured treatment outline
- multiple options presented side‑by‑side (e.g. implant vs bridge)
- phased plans (where relevant)

All descriptions MUST be patient‑friendly (plain English, not clinical codes).

### 4.2 Multimedia Explanations

Proposals MAY embed images and short videos, including patient‑specific media (e.g. intraoral photos) and educational assets.

For orthodontic contexts, proposals MAY include simulation content (where integrated).

Where multimedia assets are served via external content delivery or media provider APIs, those integrations MUST be declared as external provider dependencies and MUST comply with the External Provider API Gateway & Rate Governance policies (see §9.6).

### 4.3 Proposal Templates

Practices MAY configure proposal templates per treatment type, including mandatory wording, branding, structure, and regulatory statements.

### 4.4 Sectioned Base Template (Authoritative)

Every proposal MUST be composed from a sectioned base template to ensure consistency and prevent omission of critical content.

CTA rule (non‑negotiable): All primary CTAs (accept, approve, apply for finance, choose payment route, request call‑back, book appointment) live outside the proposal document in the app/web UI. The proposal document remains a governed narrative artefact. If a PDF is generated, CTAs may appear only as informational references (e.g. "Use the app to accept").

#### Required Sections (default)

- Cover / Context Summary (system‑controlled)
- Purpose of This Proposal (template‑controlled)
- Your Current Situation (clinician‑editable, non‑diagnostic language)
- Recommended Treatment Overview (structured)
- Treatment Options & Alternatives (required when alternatives exist)
- Treatment Stages & Timeline (required for phased care; MUST be synchronised with the PMS appointment map or an approved treatment plan template)
- Costs & Payment Routes (system‑generated; options only, no CTAs)
- Benefits, Risks & Considerations (template‑controlled core wording)
- What Happens Next (system‑controlled guidance)

#### Optional Sections (configurable per treatment type)

- Financial Considerations Explained (library blocks)
- Aftercare & Long‑Term Care (library blocks)
- Frequently Asked Questions (library blocks; optionally AI‑suggested)

### 4.5 Content Library & Click‑to‑Add Blocks (Authoritative)

Smart Treatment Proposals MUST support a content library that enables "quick‑fire" assembly of proposals from reusable, approved blocks.

A Content Block is a governed reusable unit (text, image, media, disclaimer, FAQ, aftercare guidance) that can be inserted into allowed sections.

Rules:

- Blocks are versioned and centrally managed.
- Base templates define which block types are permitted in each section.
- Mandatory blocks (e.g. regulatory statements) cannot be removed.
- Aiden MAY suggest blocks (e.g. FAQs) but humans must approve inclusion.

### 4.6 Boundary with AI Quality Monitor — Treatment Plans vs Proposals

AI Quality Monitor governs a distinct class of review‑first clinical documentation artefacts including clinical summaries, treatment plans, care plans, and hygiene plans (see AI Quality Monitor §1 Scope). These are NOT the same artefacts as Smart Treatment Proposals.

The boundary is as follows:

- A **treatment plan** produced by AI Quality Monitor is a clinical documentation output retained in the PMS/clinical record. It is a separate artefact from a Smart Treatment Proposal and is NOT governed by this module.
- Where AI Quality Monitor detects a proposal opportunity during an in‑surgery discussion, it MAY prepare a **Draft Proposal** for clinician review (see §9.4). This draft transitions into a governed Smart Treatment Proposal only after explicit clinician approval. The clinical treatment plan artefact and the resulting proposal are distinct records with separate audit trails.
- Smart Treatment Proposals MUST NOT consume or display AI Quality Monitor's clinical documentation outputs as proposal content without explicit clinician review and approval.

## 5. Delivery Surfaces & Access (Authoritative)

### 5.1 In‑Chair Presentation (Tablet App)

Proposals MAY be presented in‑chair using the Tablet App for face‑to‑face explanation.

### 5.2 Remote Review (Patient Mobile App – Primary)

Proposals MUST support delivery to the Primoro Patient Mobile App as the primary remote surface.

### 5.3 Fallback Delivery – Secure Link (Email & Optional SMS)

Where a patient is not registered on the Primoro Patient Mobile App, the system MUST fall back to sending the proposal via email containing a secure access link.

Rules:

- The secure link MUST open the same governed proposal experience as the app (web‑based).
- Identity verification mechanisms (tokenised link, expiry, secondary verification where configured) MUST be applied.
- Optional SMS notifications/tracking MAY be enabled to notify and prompt review where the proposal has not yet been opened.

Email/SMS delivery does not change proposal state; state transitions occur only through patient or staff actions inside the experience.

### 5.4 Secure Web Link Experience (Fallback)

The secure link experience MUST:

- support read‑only proposal review
- allow patient chat/questions and call‑back requests
- allow acknowledgement and acceptance where permitted
- record all views and actions in the proposal audit trail

### 5.5 Delivery & Engagement Signals

The system MUST record:

- when a proposal is delivered
- when it is opened/re‑opened
- when key sections are viewed (where instrumentation is enabled)
- when questions are submitted

These signals are used for staff visibility and may generate internal prompts (where enabled).

#### Engagement Event Contract for Consuming Modules

The following engagement events MUST be emitted as read‑only signals consumable by authorised platform modules:

| Event | Trigger |
|---|---|
| `ProposalCreated` | Proposal saved for the first time (any state) |
| `ProposalPresented` | Proposal transitions to Presented |
| `ProposalAccepted` | Proposal transitions to Accepted (see §3.2) |
| `ProposalDeclined` | Proposal transitions to Declined |
| `ProposalStalled` | Configurable inactivity threshold exceeded post‑Presented |

Campaign Manager MAY consume `ProposalCreated`, `ProposalAccepted`, `ProposalDeclined`, and `ProposalStalled` events on a read‑only basis for triggering and patient segmentation purposes. Smart Treatment Proposals does not own or execute the resulting campaign actions; Campaign Manager is solely responsible for any outbound communications triggered by these events.

Smart Dashboards MAY consume all five event types above, as well as real‑time `ProposalState` values, to power treatment pipeline conversion views (e.g. presented → accepted → declined funnels). ProposalState signals are emitted by this module; Smart Dashboards MUST NOT write back to proposal state.

### 5.6 Staff Proposal Dashboard & Team Feed (Authoritative)

The platform MUST provide a staff‑side dashboard/feed enabling clinicians, treatment co‑ordinators, and finance/admin teams to track proposal progress.

Minimum dashboard requirements:

- filter by status (Draft / Presented / Explained & Acknowledged / Accepted / Declined / Expired)
- show latest engagement (last opened, questions submitted, call‑back requested)
- show pending actions (awaiting response, awaiting review, awaiting booking)
- assign or route to the appropriate owner/team

The dashboard MUST be backed by canonical ProposalState and engagement signals and remain consistent across web portal and relevant staff workspaces.

## 6. Finance & Payment Options (Governed)

Smart Treatment Proposals MUST support configurable Payment Profiles, allowing practices to control which finance and payment‑plan options are available and under what conditions they may be used.

### 6.1 Payment & Finance Profiles (Authoritative)

Practices MAY define one or more Payment Profiles specifying:

- permitted payment mechanisms
- eligibility thresholds (e.g. minimum treatment value)
- deposit requirements
- repayment structure and cadence
- applicable treatment types

Payment Profiles are selectable per proposal and MUST be administratively configurable.

### 6.2 Supported Payment Mechanisms

A proposal MAY combine one or more of the following mechanisms, subject to profile rules:

A) Pay in Full (Card / Bank Transfer)

- Single upfront payment

B) Third‑Party Finance

- Used for higher‑value treatments
- Default minimum threshold: £250+ total plan value (configurable)
- Subject to credit approval
- Finance application initiation does not constitute treatment acceptance

C) Structured Payment Plans (Direct Debit via GoCardless)

- Used where treatment is delivered in stages over time
- Requires an upfront deposit
- Remaining balance collected via instalments

#### Alignment with Integrated Payments

The payment mechanisms listed above define the governed patient‑facing options within a proposal. The Integrated Payments module governs the downstream payment initiation surfaces (pay‑by‑link, virtual terminal, split payment drawer) and receipt delivery flows. The following rules apply at the boundary:

- Payment option presentation within a proposal (this module) is distinct from payment initiation (Integrated Payments). Selecting a payment option within a proposal does NOT initiate a payment transaction; it records the patient's intent only.
- When a patient proceeds to pay following acceptance, Integrated Payments MUST be invoked as the payment execution surface. Smart Treatment Proposals MUST NOT duplicate or replicate Integrated Payments' payment drawer or receipt UI.
- Where split or hybrid payment models are selected (see §6.3), the split configuration confirmed in the proposal MUST be passed to Integrated Payments as a structured input so that payment initiation reflects the agreed breakdown without requiring the patient to re‑enter it.
- Receipt delivery and payment history are owned by Integrated Payments; Smart Treatment Proposals retains only the proposal‑level record of the payment option chosen and the finance profile applied.

### 6.3 Hybrid Payment Models (Critical)

The system MUST support hybrid configurations, including:

- 50% deposit (cash/card) + 50% finance
- 50% finance + remaining 50% via staged Direct Debit
- Deposit + monthly Direct Debit subscription
- Deposit + quarterly Direct Debit aligned to treatment stages

Hybrid models MUST:

- clearly separate funds collected via finance vs Direct Debit
- ensure total payable equals proposal value
- remain auditable per component

### 6.4 Payment Plan Rules (Direct Debit)

Payment plans MUST:

- be available only where a deposit is taken
- align instalments to treatment delivery stages or agreed cadence
- support monthly or quarterly schedules (configurable)
- be cancellable/adjustable only via governed staff workflows

Direct Debit plans are not permitted for:

- single‑visit treatments
- treatments below a configurable minimum value

### 6.5 Treatment‑Type Constraints

Payment Profiles MUST support treatment‑type constraints, allowing rules such as:

- finance only permitted for £250+ plans
- orthodontic/implant plans eligible for subscriptions
- hygiene or low‑value procedures excluded

Rules are enforced at proposal creation and validated prior to acceptance.

### 6.6 Finance & Plan Presentation (Patient‑Facing)

Where enabled, proposals MUST:

- show available options side‑by‑side
- display representative examples (monthly amount, term, total payable)
- clearly label finance vs payment plan
- include required regulatory wording where credit is offered

### 6.7 Acceptance & Charging Separation

Rules:

- Selecting a payment option does not constitute treatment acceptance
- Finance approval does not auto‑accept a proposal

## 7. Two‑Step Consent & Acceptance Model (Authoritative)

### 7.1 Step 1 — Acknowledgement of Explanation (Mandatory)

This step confirms that:

- the plan was presented and explained
- options/costs/next steps were discussed

It is typically completed in‑chair on the Tablet App, captured via signature/approval and logged as Explained & Acknowledged.

This step does not authorise booking or commit the patient to treatment.

### 7.2 Step 2 — Acceptance to Proceed & Booking Authority

This step records a binding instruction to proceed with treatment and authorises scheduling.

Where configured and eligible, acceptance MAY also enable first‑step appointment booking.

Booking rules:

- If the first treatment stage is marked available to book, the patient MAY be shown available appointment options.
- Availability MUST respect existing Appointment Manager booking logic, including clinician availability, appointment type, and associated zone constraints.
- The patient MAY book the first‑step appointment directly as part of Step 2 where permitted.

Alternative follow‑through:

- Where direct booking is not permitted, or no suitable slots are available, the system MUST automatically create a task on the patient record for the relevant team to contact the patient and arrange booking.

Rules:

- Booking capability is conditional and configurable per treatment type and practice policy.
- Acceptance may authorise booking without requiring immediate booking action.
- Acceptance signals Treatment Pipeline to mark the linked opportunity as accepted (where linked).

### 7.3 Post‑Acceptance Stage Changes & Version Control (Authoritative)

Once a proposal has entered the Accepted state, treatment stages and timelines MUST be version‑locked.

Rules:

- Any modification to treatment stages, sequencing, or timelines after acceptance MUST create a new proposal version.
- The previously accepted version MUST remain immutable and retained for audit purposes.
- Version history MUST be accessible to authorised staff, with clear provenance (what changed, when, and by whom).
- Where required, the system MUST support reverting to a previous proposal version.
- The currently active (live) version MUST be explicitly marked and reflected consistently across:
- the proposal record
- Treatment Pipeline
- Appointment Manager booking context
- PMS traceability links

Governance:

- Creating a new version does not implicitly invalidate the previous acceptance; practices may require re‑acknowledgement or re‑acceptance based on policy.
- All version changes MUST be logged in the proposal audit trail with timestamps and user attribution.

## 8. Patient Interaction, Q&A & Call‑Backs (Build‑Contract)

### 8.1 Text & Voice Questions

Patients MAY ask questions in‑app via text and MAY submit voice questions. Voice questions MUST be captured and transcribed for staff review.

All Q&A MUST be attached to:

- the Proposal record
- the patient's Communication Hub timeline/thread context

### 8.2 AI‑Assisted Reply Drafting (Aiden)

Aiden MAY draft suggested replies for common questions and surface FAQ‑style responses.

Rules:

- Human review is mandatory before sending.
- Suggested replies must be visibly labelled as suggestions.

### 8.3 Call‑Back Requests

Patients MAY request a call‑back from within the proposal experience. This MUST create a staff‑visible task/alert with proposal context.

### 8.4 AI Concierge – Direct Dial & Out‑of‑Hours Routing (Authoritative)

Where AI Concierge is enabled, the platform MAY support one or more dedicated telephone numbers that bypass the standard IVR.

Rules:

- Dedicated numbers MAY be configured for specific use cases (e.g. proposal queries or treatment follow‑ups).
- Calls to these numbers MUST bypass the IVR and route directly to:
- the designated team queue during opening hours, or
- AI Concierge when the team is unavailable or the practice is closed.

Out‑of‑hours and fallback behaviour:

- If no human agents are available, AI Concierge MUST answer the call.
- AI Concierge MAY answer proposal questions, surface proposal status, capture notes/intent, and create follow‑up tasks.

Governance rules:

- All calls are processed through Communication Hub and telephony governance policies.
- Call outcomes, summaries, and actions MUST be logged against the patient record.
- AI Concierge MUST NOT confirm acceptance, booking, or payment autonomously unless explicitly permitted by platform policy.

## 9. Integration Contracts (Authoritative)

### 9.1 Treatment Pipeline Integration

When a proposal is Accepted:

- the linked opportunity is updated to Accepted in Treatment Pipeline (where linked)
- proposal state and timestamps become part of conversion traceability

The mechanism for this update is the `ProposalAccepted` event defined in §3.2. Treatment Pipeline Manager consumes this event and advances the linked Opportunity's stage; no direct API call from Smart Treatment Proposals to Treatment Pipeline is required beyond event emission. The `LinkedOpportunityID` carried in the event MUST match the field on the Proposal record; where it is null, no Treatment Pipeline update is triggered.

### 9.2 Appointment Manager Integration

Accepted proposals MAY unlock governed booking workflows; appointment creation remains owned by Appointment Manager.

### 9.3 PMS Integration & Traceability (e.g. Dentally)

The system MUST support PMS traceability by creating or updating a corresponding PMS record containing:

- a summary reference to the proposal
- a secure link back to the Primoro proposal as the authoritative artefact

When a proposal is revised or accepted, the PMS record SHOULD reflect the revised/accepted status and provide access to the signed artefact via link or stored document reference (as configured).

### 9.4 AI Quality Monitor Assisted Drafting (Optional – Review‑First)

If AI Quality Monitor is enabled, it MAY detect a proposal opportunity during an in‑surgery discussion and prepare a Draft Proposal for clinician review.

Rules:

- AI Quality Monitor creates a proposal only in Draft state.
- The clinician receives a non‑blocking notification/popup indicating a draft has been prepared for review.
- The clinician MUST review, edit, and explicitly convert the draft into a presented proposal.
- AI Quality Monitor MUST NOT present, send, or accept proposals autonomously.
- All AI‑assisted drafting provenance is recorded in the proposal audit trail.

For the boundary between AI Quality Monitor's clinical documentation artefacts and Smart Treatment Proposals, see §4.6.

### 9.5 Smart Dashboards Integration

Smart Dashboards consumes ProposalState signals and conversion events from this module to power treatment pipeline conversion views (e.g. presented → accepted → declined funnels for the TCO Dashboard).

Rules:

- Smart Treatment Proposals MUST emit `ProposalCreated`, `ProposalPresented`, `ProposalAccepted`, `ProposalDeclined`, and `ProposalStalled` events as defined in §5.5 in a form consumable by Smart Dashboards.
- Smart Dashboards is the exclusive consumer of treatment pipeline conversion data originating from this module; no other module may re‑aggregate or re‑publish these signals on its behalf.
- Smart Dashboards MUST NOT write back to proposal state; its consumption is strictly read‑only.
- The ProposalState values exposed to Smart Dashboards MUST be sourced from the canonical Proposal State Machine (§3.2) and MUST remain consistent with the staff dashboard/feed (§5.6).

### 9.6 Financial Insights Integration

Financial Insights consumes proposal acceptance and finance‑profile data for revenue forecasting and outstanding collections tracking.

Rules:

- When a Proposal transitions to Accepted and a payment profile or finance plan has been selected, Smart Treatment Proposals MUST emit an event containing: `ProposalID`, `PatientID`, `AcceptedAt`, `TotalProposalValue`, `SelectedPaymentProfileID`, and a structured breakdown of any hybrid payment components (finance portion, Direct Debit portion, upfront deposit).
- Financial Insights MAY use these events to populate outstanding amount tracking and revenue timing forecasts. Smart Treatment Proposals does not own or calculate revenue forecasts; that responsibility belongs to Financial Insights.
- Finance plan creation intent and Direct Debit schedule intent (logged in the audit trail per §10) MUST be emitted in a form accessible to Financial Insights for collections delay monitoring.
- Financial Insights MUST NOT alter proposal state or payment profile configuration.

### 9.7 External Provider API Gateway & Rate Governance

Where Smart Treatment Proposals integrates with external content delivery, media hosting, or document generation providers (e.g. for multimedia explanations as described in §4.2), those integrations MUST be declared as external provider dependencies and governed as follows:

- All external provider API calls MUST be routed through the External Provider API Gateway.
- Each integration MUST declare a traffic class (e.g. interactive/patient‑facing, background/batch) appropriate to its use case.
- Rate limits, retry policies, and failure handling MUST comply with the platform's Rate Governance policies.
- External provider dependencies used for patient‑facing content (e.g. media delivery during a proposal review session) MUST be classified as interactive traffic and MUST have defined fallback behaviour (e.g. graceful degradation to static content) if the provider is unavailable.
- New external provider integrations introduced by this module MUST be registered in the External Provider API Gateway before production deployment.

### 9.8 Referral Manager Integration

Referral Manager and Smart Treatment Proposals are distinct modules with separate artefact types and governance flows. The boundary is as follows:

- A Smart Treatment Proposal is a patient‑facing conversion artefact governing treatment acceptance within the practice. An outbound referral governed by Referral Manager is a clinical communication to an external provider.
- Where a treatment stage within an accepted proposal requires onward referral (e.g. specialist consultation), the acceptance of the proposal MAY act as a trigger for Referral Manager to initiate a referral workflow. This is a one‑way signal: Smart Treatment Proposals emits the `ProposalAccepted` event; Referral Manager MAY consume it where configured to do so for relevant treatment types.
- Referral Manager MUST NOT alter proposal state. Smart Treatment Proposals MUST NOT execute or own referral artefacts.
- Where an inbound referral from Referral Manager results in a treatment recommendation requiring a proposal, the referring record MAY be linked to the resulting proposal via `LinkedOpportunityID` or an equivalent cross‑reference, providing traceability between referral source and proposal outcome.
- All AI‑drafted referral content governed by Referral Manager remains subject to Referral Manager's own review‑first policies and is distinct from AI‑assisted proposal drafting governed by this module.

## 10. Audit, Compliance & Retention

The module MUST record (immutable):

- proposal creation and edits (with versioning)
- delivery method (tablet/app/web/email link)
- each proposal open/re‑open event
- acknowledgements and signatures
- acceptance/decline events
- payment profile selection and payment option selection
- finance interactions (viewed options, application initiated)
- payment plan creation intent and direct debit schedule intent (where enabled)
- questions submitted (text and voice)
- call‑back requests
- AI Quality Monitor drafting provenance (where enabled)

All audit data must remain inside Primoro's secure ecosystem and be exportable for disputes/audits.

## 11. Access Control & Security

Access MUST be governed by Access Manager and role‑based permissions:

- staff access to proposals, signatures, and audit logs
- patient access via app login or secure web link verification

Documents and transcripts MUST be encrypted at rest and in transit, with access events logged.

## 12. Explicit Non‑Goals

Smart Treatment Proposals does NOT:

- diagnose conditions or chart clinically
- bypass clinical consent requirements where separate statutory consent forms are required
- automate marketing outreach (campaigns remain owned by Campaign Manager)
- replace the Patient App with PDFs as the primary workflow
- ingest its artefacts into Document Hub (each module retains its own governed artefacts within its own storage boundary)

## 13. Build‑Contract Guarantees

Engineering MUST ensure:

- proposal state integrity and valid state transitions
- immutable audit trails
- strict role‑based access control
- acceptance and signatures cannot be altered after capture
- finance application initiation never auto‑accepts a proposal
- booking is never created outside Appointment Manager governance

## 14. Acceptance Criteria (QA Contract)

Smart Treatment Proposals v2.1 is complete when:

- Proposals can be created using the sectioned base template, with mandatory sections enforced and optional sections configurable.
- Content blocks can be inserted from the content library and mandatory blocks cannot be removed.
- Proposals can be delivered in‑chair (Tablet App), in‑app, and via secure email link fallback with optional SMS notifications.
- Proposal engagement signals are captured and visible in a staff dashboard/feed.
- Staff can filter proposals by status and route/assign ownership to the correct team.
- Two‑step model is enforced:
- Step 1 acknowledgement is captured and recorded as Explained & Acknowledged
- Step 2 acceptance is recorded distinctly and reuses signature by default
- Step 2 can optionally offer first‑step booking (zone‑aware) when permitted, otherwise a booking follow‑up task is created.
- Patients can submit text and voice questions; voice questions are transcribed and routed to staff with audit traceability.
- Payment Profiles enforce finance thresholds, deposit requirements, treatment constraints, and hybrid models where enabled.
- Selecting a payment option or applying for finance does not constitute acceptance.
- On acceptance, a `ProposalAccepted` event is emitted carrying `ProposalID`, `LinkedOpportunityID`, `PatientID`, `AcceptedAt`, and payment breakdown; Treatment Pipeline, Financial Insights, and (where configured) Referral Manager consume this event correctly.
- `ProposalCreated`, `ProposalPresented`, `ProposalDeclined`, and `ProposalStalled` events are emitted and consumable by Smart Dashboards and Campaign Manager in read‑only mode.
- Hybrid payment configurations are passed as structured inputs to Integrated Payments on payment initiation; Smart Treatment Proposals does not duplicate Integrated Payments' payment drawer or receipt UI.
- Acceptance updates Treatment Pipeline opportunity status where linked; booking remains governed by Appointment Manager.
- PMS traceability links are created/updated to support audit visibility in the clinical system.
- If AI Quality Monitor is enabled, it can create Draft proposals only and clinicians receive a non‑blocking notification for review; drafts cannot auto‑present or auto‑accept; the boundary between AI Quality Monitor clinical documentation artefacts and proposal artefacts is enforced.
- If AI Concierge direct‑dial is enabled, calls bypass IVR and are logged and routed according to governance rules.
- External provider API integrations (e.g. media delivery) are registered with the External Provider API Gateway, declare a traffic class, and implement fallback behaviour for patient‑facing surfaces.
- Proposal artefacts are retained within Smart Treatment Proposals' own secure storage boundary and are not ingested into Document Hub.
- End of Document – Smart Treatment Proposals – Technical Specification v2.1 (Design‑Final)

## 15. Form Template Library (Authoritative)
The forms module MUST ship with a pre-populated library of form templates so that practices can begin using forms immediately without building them from scratch.

### Seed Templates

- The initial template library is seeded from Foxbury's existing form documents, covering the standard forms required for dental practice operations.
- Seed templates are provided by the platform operator at deployment time.
- Each seed template contains pre-authored content (all required sections and wording) and is ready to use out-of-the-box.

### Branding Inheritance

- Templates MUST automatically inherit the practice's top-level branding configuration (logo and font) from the platform branding settings.
- No per-template branding configuration is required; branding is applied at render/export time.
- The rendered form must visually identify as coming from the practice.

### Clone and Edit

- Practices MAY clone any template to create a practice-specific version.
- Cloned templates are fully editable via the drag-and-drop form builder.
- The original seed template remains unchanged and available to all practices.
- Practices MAY also create entirely new forms from scratch using the drag-and-drop builder.

### Template Import (Post-MVP Investigation)

- A capability to upload an existing document (e.g. a Word file) and have the system parse and auto-generate a draft form for review, tweaking, and saving is a desirable future feature.
- This feature requires a detailed specification before implementation and is not committed to MVP.
- John confirmed feasibility is possible with a detailed spec; Harry confirmed intent.

Live preview