Recall & Reconnect – Technical Specification

1. Module Purpose & Scope (Authoritative)

Recall & Reconnect is Primoro's care-continuity automation module. It ensures patients attend routine care at the right clinical intervals (Recall) and are respectfully re-engaged if they lapse or disengage (Reconnect). The module replaces manual recall lists, PMS recall emails, spreadsheets, and ad-hoc chasing, while maintaining a calm, relationship-led healthcare tone.

It governs:

• Recall and reconnect state computation, determining patient eligibility (Not Due / Due / Overdue / Inactive)
• Enrolment, progression, and exit of patients through approved recall and reconnect journeys
• Selection of pre-approved recall and reconnect communication templates
• Emission of auditable compliance and attendance events consumable by downstream modules

It explicitly does not:

• Execute message delivery or channel escalation — owned by Patient Outreach Manager
• Own booking, appointment availability, or diary integrity — owned by Appointment Manager
• Own consent, opt-out, and channel preference enforcement — owned by User & Access / Preferences
• Receive or log inbound patient replies directly — owned by Communication Hub
• Compute, own, or modify care plan status, pricing, or entitlements — owned by Care Plan Subscriptions
• Initiate marketing or promotional campaigns — owned by Campaign Manager

2. Ownership & Responsibilities

2.1 Recall & Reconnect IS Responsible For

• Computing recall eligibility state for each patient (Not Due / Due / Overdue / Inactive)
• Determining outreach sub-states (Notified / Viewed / Engaged / Booked / Needs Personal Follow-up)
• Controlling enrolment, progression, and exit from individual recall and reconnect journeys
• Enforcing the single-journey constraint (one active Recall/Reconnect journey per patient at a time)
• Suppressing recall outreach when a Care Plan entitlement is not yet available
• Consuming entitlement-availability and suppression events from the event bus and re-evaluating eligibility accordingly
• Emitting an outcome event to Loyalty Insights when a patient journey originating from a Loyalty Insights handoff reaches a terminal state
• Publishing patient enrolment events to the shared event bus so Campaign Manager can apply equivalent suppression
• Generating non-clinical task creation requests when automation cannot progress safely
• Providing a management dashboard exposing journey state, automation health, and staff hand-off reasons
• Maintaining a complete, immutable audit trail of all state transitions and outreach events

2.2 Recall & Reconnect IS NOT Responsible For

• Message delivery, channel ordering, send-time optimisation, throttling, or suppression rules — owned by Patient Outreach Manager
• Creating or modifying clinical notes — prohibited; no module is authorised to perform this on behalf of Recall & Reconnect
• Writing back to PMS systems — PMS recall systems must be disabled by the practice; Primoro is the single source of truth
• Booking, availability management, or diary integrity — owned by Appointment Manager
• Reward logic or points accrual triggered by recall compliance events — owned by Rewards Manager
• Detecting disengagement patterns that initiate handoffs — owned by Loyalty Insights
• Consent, opt-out, and channel preference enforcement — owned by User & Access / Preferences
• Promotional or campaign communications — owned by Campaign Manager

3. Core Objects (Normative)

3.1 Patient Recall Record (Canonical Artefact)

A Patient Recall Record is a governed digital artefact representing one patient's current recall eligibility and outreach journey state within Recall & Reconnect.

Minimum required fields:

• RecallRecordID
• PatientID (FK to patient)
• RecallState (Not Due / Due / Overdue / Inactive)
• OutreachSubState (Notified / Viewed / Engaged / Booked / Needs Personal Follow-up)
• TriggerReason (recall due date / inactivity / DNA)
• EnrolledAt
• LastTransitionAt
• LastTransitionBy (system / user / role)
• EscalationFlag (boolean)
• JourneyOrigin (standard / Loyalty Insights handoff reference)
• AuditTrail (immutable)

3.2 Patient Recall State Machine (Authoritative)

Primary recall states:

• Not Due
• Due
• Overdue
• Inactive

Outreach sub-states:

• Notified
• Viewed
• Engaged
• Booked
• Needs Personal Follow-up

Rules:

• All state transitions are automatic, atomic, timestamped, and auditable.
• A patient cannot hold more than one active Recall/Reconnect journey simultaneously.
• Reconnect MUST NOT trigger while a Recall journey is active for the same patient.
• Viewing without booking advances sub-state to Viewed; any inbound reply advances sub-state to Engaged and halts escalation.
• Booking immediately exits the journey and records the terminal state as Booked.
• Re-enrolment requires a material state change (e.g. a new recall due date); re-enrolment on the basis of the previous trigger is prohibited.
• After terminal escalation failure with no engagement, the system MUST generate a Needs Personal Follow-up work item and halt; re-enrolment requires manual staff intervention.
• Escalation attempts are capped per journey; infinite looping is prohibited.

4. Trigger Model

4.1 Recall Triggers

Recall is time- and event-based. The next due date is calculated from:

• The date of the patient's last completed appointment
• The clinician-defined recall interval
• The Care Plan visit cadence where an active Care Plan is present

4.2 Reconnect Triggers

Reconnect is initiated when:

• No completed appointments exist within the practice-configured inactivity window
• A cancelled or DNA appointment has not been followed by a rebooked appointment

4.3 Care Plan Waiting-Period & Contribution Gating (Authoritative)

Recall & Reconnect MUST respect waiting-period and minimum-contribution rules supplied by Care Plan Subscriptions before initiating any outreach against a Care Plan entitlement.

• If a Care Plan entitlement is in a Not Yet Available state (the patient has not met the minimum contribution threshold or the waiting period has not elapsed), Recall & Reconnect MUST NOT trigger recall outreach for that entitlement.
• Where a Care Plan cadence would otherwise produce a recall trigger, the system MUST check the entitlement availability status supplied by Care Plan Subscriptions. If the status is Not Yet Available, the recall trigger is suppressed and the patient's state remains Not Due until the entitlement unlocks.
• When the entitlement transitions to available, Care Plan Subscriptions emits a status update event; Recall & Reconnect MUST consume this event and re-evaluate recall eligibility at that point.
• No anticipatory outreach is permitted on the basis of a pending or approaching entitlement; messaging MUST NOT be sent for entitlements that have not yet unlocked.

4.4 Loyalty Insights Handoff Triggers

Loyalty Insights may initiate a handoff to Recall & Reconnect when disengagement patterns are detected. Recall & Reconnect MUST:

• Accept the handoff reference and record it against the patient journey (JourneyOrigin field).
• Emit an outcome event when the journey reaches a terminal state (Booked, Needs Personal Follow-up, or journey exit), including the originating handoff reference, the terminal state reached, and a timestamp.
• Publish this outcome event to the shared event bus; Recall & Reconnect does not write directly into Loyalty Insights' data store.

5. Outreach Orchestration

5.1 Relationship to Patient Outreach Manager

Recall & Reconnect uses the Patient Outreach Manager campaign engine but exposes only pre-approved recall and re-engagement workflows. Key constraints:

• No arbitrary campaign creation by this module
• No promotional templates
• No cross-module campaign blending
• Each patient can be enrolled in only one active Recall/Reconnect journey at a time

5.2 Channel Strategy (Authoritative)

Primary channel — Primoro Patient Mobile App:

• Push notification deep-linking into a contextual in-app message
• Clear primary action: Book or Ask a question
• No guilt or urgency language

Intelligent fallback:

If no app engagement occurs within the configured window:

• SMS
• then Email (where enabled)

Fallback stops immediately on engagement. All channel escalation rules are governed centrally by Patient Outreach Manager.

5.3 Campaign Manager Suppression & Collision Prevention (Authoritative)

Recall journeys MUST NOT run in parallel with Campaign Manager activity for the same patient. This is technically enforced as follows:

• Recall & Reconnect MUST subscribe to suppression, consent-revocation, and journey-exit events published by Campaign Manager via the shared event bus.
• On receipt of a suppression or consent-revocation event for a patient with an active Recall/Reconnect journey, the system MUST immediately pause or exit that journey (per event type) and record the reason against the patient's journey audit trail.
• When Recall & Reconnect enrols a patient in a journey, it MUST publish an enrolment event to the shared event bus so Campaign Manager can apply equivalent suppression on its side.
• If a Campaign Manager exit event arrives after a Recall/Reconnect journey has already reached a terminal state, no action is required beyond logging the event as received.
• Suppression applied via this mechanism is subject to the same preference and consent rules enforced by User & Access / Preferences and is fully auditable.

5.4 Failure Modes & Safeguards

Channel failure:

• If push delivery fails, fallback proceeds per Patient Outreach Manager configuration.
• If a channel is opted out, escalation skips that channel.
• If all channels are unavailable, the journey pauses (no looping).

Partial engagement:

• Viewing without booking advances sub-state to Viewed.
• Any reply advances sub-state to Engaged and halts further escalation.

Infinite loop prevention:

• Escalation attempts are capped per journey.
• Re-enrolment requires a material state change.
• Manual staff intervention is required after terminal failure.

6. Delivery Surfaces & Access (Authoritative)

6.1 Web Portal — Management Dashboard

Recall & Reconnect MUST provide a dedicated operational dashboard within Primoro. Authorised staff must be able to:

• View the current recall population breakdown (Due / Overdue / Inactive)
• See live journey status per patient (Notified / Viewed / Engaged / Booked)
• Identify patients requiring personal follow-up
• Monitor automation health (active journeys, paused journeys, failures)
• Understand where and why hand-offs to staff have occurred

Automation transparency: For each patient journey the dashboard must surface:

• Trigger reason (recall due / inactivity / DNA)
• Last message sent and channel used
• Next scheduled action (if any)
• Whether automation is active, paused, or completed

Staff hand-offs: When automation cannot progress safely:

• A clear work item is created with the reason for hand-off explicitly shown.
• Ownership is assigned using standard task patterns.
• Staff must never need to infer state by reading message threads alone.

6.2 Tablet App

Recall & Reconnect does not expose a primary authoring surface on the in-practice tablet; staff access to recall state and hand-off work items is via the web portal dashboard.

6.3 Patient Mobile App

• Recall and reconnect journeys are delivered app-first via push notification and in-app message.
• The patient's primary action surfaces are: Book and Ask a question.
• No promotional or campaign content is surfaced through these journeys.

6.4 Engagement Signals

The module emits engagement signals including: journey enrolment, message delivery confirmation (via Patient Outreach Manager), sub-state transitions (Notified → Viewed → Engaged → Booked), escalation events, hand-off events, and journey exit events. These are visible in the management dashboard and consumable by downstream modules via the shared event bus.

7. AI Boundaries (Non-Negotiable)

Module does not embed AI surfaces directly.

Recall & Reconnect is a rules-based, state-driven module. Trigger evaluation, state transitions, template selection, and escalation sequencing are all governed by deterministic configuration and the state machine defined in §3.2. No AI or machine-learning inference is involved in any patient eligibility or outreach decision.

AI MAY NOT:

• Auto-decide recall eligibility or outreach timing
• Select or modify communication templates without explicit practice configuration
• Bypass governance, audit, or access checks
• Make commitments on behalf of the practice

8. Audit & Compliance

The system MUST log:

• All recall state transitions (Not Due / Due / Overdue / Inactive), with actor (system or staff), role, and timestamp
• All outreach sub-state transitions (Notified / Viewed / Engaged / Booked / Needs Personal Follow-up), with timestamp
• All outreach events initiated, including channel used and delivery outcome
• All suppression and consent-revocation events received from Campaign Manager or User & Access / Preferences, and the resulting journey action taken
• All Care Plan entitlement gating decisions (trigger suppressed / trigger allowed), with entitlement status at time of evaluation
• All Loyalty Insights handoff receipts and outcome events emitted
• All task/work item creation requests, with trigger reason
• All journey exit events (terminal state, reason, timestamp)
• All enrolment events published to the shared event bus
• Patient consent and channel preference state at the time each outreach event was initiated

Audit logs MUST be immutable and exportable for inspection. All outreach is subject to consent and channel preference enforcement via User & Access / Preferences.

Operational versus non-essential messaging classification MUST be respected in accordance with platform consent policy. The full patient communication audit trail must be accessible to authorised staff via the management dashboard and to compliance functions via export.

9. Access Control

Access control is enforced by User & Access / Preferences. The following capability boundaries apply:

• Read recall population and journey state: Clinical and administrative staff with recall visibility permissions
• Trigger manual re-evaluation or hand-off: Authorised clinical or administrative staff
• Pause or exit a patient journey manually: Authorised staff (administrative or clinical lead)
• Configure recall intervals and inactivity thresholds: Practice administrator via Admin Control Plane
• Enable optional integrations (e.g. physical mail, future): Practice administrator via Admin Control Plane
• Create or modify communication templates: Not permitted within this module; templates are managed by Patient Outreach Manager
• Delete a Patient Recall Record: Not permitted; records are immutable; state transitions are the only permitted mutation

MFA requirements for sensitive operations are governed by User & Access / Preferences policy and apply to any action that pauses, exits, or re-enrols a patient journey.

10. Integration Contracts

10.1 Inbound (this module consumes from)

10.2 Outbound (this module emits to)

10.3 PMS Boundary

Recall state computation, outreach orchestration, and patient journey management are owned entirely by Primoro. PMS recall emails and reminder systems MUST be disabled by the practice when Recall & Reconnect is active. No clinical notes or appointment data are written back to the PMS by this module. Primoro is the single source of truth for recall status.

11. Explicit Non-Goals

• Physical letter fulfilment: Recall & Reconnect does not require and must not depend on paid third-party postal integrations by default. Physical letter services may be supported in future as an optional, per-practice integration that is explicitly enabled, non-blocking, fully auditable, and treated as a terminal fallback only. Unless explicitly enabled, the module operates entirely digitally.
• Marketing and lead acquisition campaigns: This module is not a marketing campaign engine and not a lead acquisition tool. Promotional content is out of scope; owned by Campaign Manager.
• Clinical note creation or modification: Out of scope; no module is authorised to perform this on behalf of Recall & Reconnect.
• PMS writeback: Out of scope; PMS recall systems are to be decommissioned from recall duties upon adoption of this module.
• Reward logic and points accrual: Out of scope; owned by Rewards Manager, which consumes recall compliance events independently.

12. Versioning & Governance

This specification is owned by: the Recall & Reconnect module owner (Post-MVP tier).

Changes to this spec require:

• Review by the Post-MVP module owner
• Impact analysis across declared related modules (see /propose)
• Version bump (patch / minor / major) depending on scope of change

13. Build Contract (Engineering & QA)

13.1 Canonical Data Model

patient_recall_record (
  recall_record_id        UUID PRIMARY KEY,
  patient_id              UUID NOT NULL,           -- FK to patient
  recall_state            ENUM(
                            'not_due',
                            'due',
                            'overdue',
                            'inactive'
                          ) NOT NULL,
  outreach_sub_state      ENUM(
                            'notified',
                            'viewed',
                            'engaged',
                            'booked',
                            'needs_personal_followup'
                          ),
  trigger_reason          ENUM(
                            'recall_due_date',
                            'inactivity',
                            'dna'
                          ) NOT NULL,
  journey_origin          TEXT,                    -- 'standard' or Loyalty Insights handoff ref
  escalation_flag         BOOLEAN NOT NULL DEFAULT FALSE,
  enrolled_at             TIMESTAMPTZ NOT NULL,
  last_transition_at      TIMESTAMPTZ NOT NULL,
  last_transition_by      TEXT NOT NULL,           -- system / user ID / role
  care_plan_entitlement_status TEXT,               -- snapshot at trigger evaluation
  audit_trail             JSONB NOT NULL           -- immutable append-only log
)

13.2 Core Behaviour Rules

1. A patient MUST NOT be enrolled in more than one active Recall/Reconnect journey at any time.
2. Reconnect MUST NOT be triggered while a Recall journey is active for the same patient.
3. When a Care Plan entitlement status is Not Yet Available, the recall trigger for that entitlement MUST be suppressed and the patient's recall state MUST remain Not Due.
4. When Care Plan Subscriptions emits an entitlement-available event, Recall & Reconnect MUST re-evaluate recall eligibility within the same processing cycle.
5. No anticipatory outreach is permitted; messaging MUST NOT be sent for entitlements that have not yet unlocked.
6. Any inbound patient reply (routed via Communication Hub) MUST advance the outreach sub-state to Engaged and MUST halt further channel escalation.
7. A booking event from Appointment Manager MUST immediately exit the journey and record the terminal state as Booked.
8. Escalation attempts per journey MUST be capped at the practice-configured maximum; the journey MUST NOT loop after the cap is reached.
9. After terminal escalation failure with no engagement, the system MUST generate a Needs Personal Follow-up work item via Task Manager and MUST halt the journey.
10. Re-enrolment after a terminal state MUST require a material state change (e.g. a new recall due date); re-enrolment on the same trigger is prohibited without manual staff intervention.
11. On receipt of a Campaign Manager suppression or consent-revocation event, an active Recall/Reconnect journey MUST be paused or exited immediately and the reason MUST be recorded in the audit trail.
12. When a patient is enrolled in a journey, Recall & Reconnect MUST publish an enrolment event to the shared event bus.
13. When a journey originating from a Loyalty Insights handoff reaches a terminal state, Recall & Reconnect MUST emit an outcome event containing the handoff reference, terminal state, and timestamp.
14. All state mutations MUST be atomic, timestamped, and recorded in the immutable audit trail.
15. Recall compliance and appointment attendance events MUST be emitted to the shared event bus independently of whether Rewards Manager is available; Recall & Reconnect MUST NOT have a runtime dependency on Rewards Manager.

13.3 Configuration Surfaces

• Practice-level settings (Admin Control Plane):
• Recall interval per appointment type / clinician
• Inactivity threshold for Reconnect triggers
• DNA rebooking window
• Escalation attempt cap per journey
• App engagement window before fallback channel is activated
• Physical mail integration toggle (disabled by default)

• Enable / disable SMS and email fallback channels

• Per-practice, system-level (governed by Patient Outreach Manager):

• Channel ordering and send-time rules
• Throttling and global suppression rules

• Approved recall and reconnect template library

• Per-user preferences (User & Access / Preferences):

• Channel opt-out and consent state (read-only by this module; enforced at outreach initiation)

13.4 Filtering & Views

The management dashboard MUST support the following filters:

• Recall state: Due / Overdue / Inactive
• Outreach sub-state: Notified / Viewed / Engaged / Booked / Needs Personal Follow-up
• Trigger reason: Recall due date / Inactivity / DNA
• Automation status: Active / Paused / Completed / Failed
• Journey origin: Standard / Loyalty Insights handoff
• Date range: Enrolled at / Last transition at

Saved views for "Needs Follow-up Today" and "Stalled Journeys" MUST be available as default views for staff without requiring manual filter configuration.

13.5 Module Extension Map

• Physical mail as a terminal fallback channel may be added as an optional, per-practice integration without modifying the core state machine or channel escalation contract.
• Additional trigger types (e.g. lab result-based recall) may be introduced as new TriggerReason enum values without breaking existing journey records.
• Additional outreach sub-states must be additive only and must not reorder or remove existing states.
• Loyalty Insights handoff contracts are versioned via the shared event bus schema; changes require a coordinated version bump with the Loyalty Insights module.

13.6 Acceptance Criteria

The build of Recall & Reconnect is complete when:

• [ ] Patient recall states (Not Due / Due / Overdue / Inactive) update automatically from appointment and Care Plan events
• [ ] Care Plan entitlement gating correctly suppresses outreach when status is Not Yet Available and re-evaluates on entitlement-available events
• [ ] App-first recall journeys operate end-to-end including push notification and in-app message delivery via Patient Outreach Manager
• [ ] Fallback channels escalate correctly per configuration and halt immediately on engagement
• [ ] A patient cannot be enrolled in more than one active Recall/Reconnect journey simultaneously (enforced at data layer)
• [ ] Campaign Manager suppression and consent-revocation events pause or exit active journeys and are recorded in the audit trail
• [ ] Enrolment events are published to the shared event bus on each journey enrolment
• [ ] Loyalty Insights outcome events are emitted for all journeys originating from handoffs
• [ ] Recall compliance and appointment attendance events are emitted independently of Rewards Manager availability
• [ ] All state transitions are atomic, timestamped, and recorded in the immutable audit trail
• [ ] Management dashboard surfaces recall population, journey state, automation health, and hand-off reasons
• [ ] Needs Personal Follow-up work items are generated via Task Manager when automation reaches terminal failure
• [ ] Escalation cap is enforced; infinite looping is prevented
• [ ] AI boundaries in §7 are enforced (no AI inference in eligibility or outreach decisions)
• [ ] Access control is enforced per §9
• [ ] All non-functional requirements in §14 are met

14. Non-Functional Requirements

• Performance: State re-evaluation on incoming trigger events (appointment completion, Care Plan entitlement change, Campaign Manager suppression) MUST complete within a latency consistent with near-real-time processing. Specific latency targets to be defined by engineering during build; the dashboard MUST reflect current state without requiring manual refresh.
• Reliability: The module MUST degrade gracefully when downstream modules (e.g. Rewards Manager, Loyalty Insights) are unavailable; outreach and state transitions MUST continue unaffected. Journey pause and the Needs Personal Follow-up escalation path MUST be available even when Patient Outreach Manager delivery is temporarily degraded. Availability target to be set in the platform SLA; this module is classified as a core care-continuity function.
• Scalability: The module MUST support multi-practice, multi-site deployments without shared recall state across tenants. Recall population queries MUST remain performant as patient roster size grows. Per-tenant isolation of recall records and event bus topics is required.
• Security: All patient-bound recall data MUST be encrypted at rest and in transit. Secrets and integration credentials MUST be managed via the platform secrets management service. No patient PII is to be included in shared event bus payloads beyond the patient identifier required for correlation.
• Privacy: The module MUST honour patient consent and opt-out state as enforced by User & Access / Preferences before any outreach event is initiated. Recall records are patient-bound and subject to platform data retention and GDPR subject-access-request policies. The entitlement status snapshot recorded at trigger evaluation must be retained as part of the audit trail for the life of the record, consistent with platform retention policy.
• Observability: The module MUST export metrics covering: active journey count by state, escalation cap breaches, journey exit reasons (Booked / Needs Personal Follow-up / suppressed), event bus publish and consume latency, and dashboard query latency. Structured logs MUST be emitted for all state transitions. Distributed traces MUST span across the Patient Outreach Manager outreach initiation boundary to enable end-to-end delivery debugging.

15. Open Questions

1. Escalation attempt cap: What is the default practice-level cap on escalation attempts per journey? The original states the cap is configurable but does not specify a default value. This must be defined before build.
2. App engagement window: What is the default window (in hours or days) that must elapse without app engagement before the fallback channel (SMS) is activated? The original states this is configurable but provides no default.
3. Inactivity threshold: What is the default inactivity window (in months) that triggers a Reconnect journey? The original identifies this as a configurable practice-level setting but does not specify a default.
4. Physical mail future integration: If and when physical letter services are added as an optional per-practice integration, which third-party postal service(s) are candidates, and what data-protection assessment is required? The original defers this entirely.
5. Dashboard performance targets: Specific latency targets for the management dashboard and state re-evaluation pipeline are not defined in the original. These must be agreed between product and engineering before the build contract is locked.
6. Loyalty Insights event bus schema versioning: The outcome event contract between Recall & Reconnect and Loyalty Insights is declared but the shared event bus schema version and governance process for coordinated changes is not specified in the original.
7. Campaign Manager collision detection — timing window: The original requires that Recall & Reconnect subscribe to Campaign Manager suppression events, but does not specify how a collision is handled if both an enrolment and a suppression event are in-flight simultaneously. The conflict-resolution rule needs to be defined.