SmileCue

Jurisdiction Rules

Automatically applies state- and country-specific TCPA requirements, quiet hours, and consent classes (informational vs. marketing) based on patient location and channel. Eliminates guesswork for staff and reduces legal exposure by ensuring every send follows the right rule set without manual configuration.

Requirements

Jurisdiction Resolution Engine

"As an office manager, I want SmileCue to automatically determine each patient’s applicable jurisdiction and local time so that messages always follow the correct rules without manual setup."

Description

Determine the correct legal jurisdiction and local time context for each intended communication based on patient data (verified address, phone country code/area code, and stored timezone), with robust fallback logic when signals conflict or are missing. The engine outputs a normalized jurisdiction key (state + country) and timezone to downstream services and caches results for performance. It integrates with SmileCue’s orchestration layer so every SMS, email, and voice attempt is tagged with the jurisdiction before rule evaluation. It must handle edge cases (telemedicine across borders, relocated patients, PO Boxes, daylight saving changes) and expose confidence levels to allow conservative defaults (suppress or downgrade to informational). Expected outcome: every send path reliably knows “where the law applies” without staff input.

Acceptance Criteria

Precedence-Based Jurisdiction Resolution and Normalized Output

Rule: The engine resolves jurisdiction using precedence: verified physical address (non-PO Box) > phone number metadata (country code and NANP area code) > stored timezone > practice default. Rule: The engine outputs jurisdiction_key in the format COUNTRY-PRIMARY_SUBDIVISION (e.g., "US-CA"); if subdivision unavailable, output COUNTRY only (e.g., "CA"). Rule: The engine outputs timezone as a valid IANA tz identifier (e.g., "America/Los_Angeles"). Rule: Given identical inputs, the engine returns identical outputs (deterministic) across runs. Rule: If all signals are missing, the engine returns practice default jurisdiction_key and timezone with confidence="low" and reason_codes including "no_signals".

Conflict Resolution with Confidence Levels

Given two or more signals disagree on jurisdiction, When resolution occurs, Then the engine selects the highest-precedence signal and emits confidence levels: high when the top two signals agree; medium when only the top signal is usable; low when falling back to practice default or stored timezone only. Rule: The engine includes reason_codes enumerating which signals were used, which were discarded, and why (e.g., "phone_country_mismatch", "tz_only", "address_unverified_po_box"). Rule: The engine emits conflict_summary=true when any lower-precedence signal disagrees with the chosen jurisdiction. Rule: Confidence and reason_codes are included in the response and the orchestration tag for downstream use.

DST-Safe Timezone Resolution

Given a send scheduled at 2025-03-09T09:55:00Z for a patient in "America/Los_Angeles", When resolution occurs, Then local time is 01:55 and quiet-hour evaluation uses PST; given 2025-03-09T10:05:00Z, then local time is 03:05 and PDT applies. Given a send scheduled at 2025-10-26T00:30:00Z for a patient in "Europe/Berlin", When resolution occurs, Then local time and offset reflect CET/CEST accurately across the fall-back hour with no duplicate or skipped hour errors. Rule: The timezone database is versioned and updated at least monthly; tzdb_version is included in diagnostics.

Caching and Invalidation for Jurisdiction Resolution

Rule: Resolutions are cached by patient_id plus signal fingerprints (address_hash, phone_hash, tz_value) with a TTL of up to 24h. Rule: Cache entries are invalidated within 5 seconds of any change to address, phone, or stored timezone. Rule: After invalidation, subsequent resolutions use updated signals and emit cache_status="miss_fresh". Rule: In steady state with unchanged profiles, P95 resolution latency is <= 50 ms and cache_hit_rate >= 80% under production-like load.

Pre-Rule Orchestration Tagging Across Channels

Given an SMS, email, or voice attempt enters orchestration, When the engine resolves jurisdiction, Then the attempt is tagged with jurisdiction_key, timezone, confidence, and reason_codes before any TCPA/quiet-hour rule evaluation. Rule: If the engine cannot produce a jurisdiction_key and timezone, the attempt is not dispatched; orchestration marks it blocked with error_code="jurisdiction_unresolved". Rule: Tags persist on the attempt record and are available in audit logs and analytics. Rule: Tagging is idempotent; re-evaluating the same attempt with unchanged inputs does not create duplicate tags.

Cross-Border Telemedicine and Mixed Signals

Given appointment_type="telehealth" and the patient’s verified address country differs from the practice country, When resolving jurisdiction, Then the engine prefers the patient’s verified address per precedence and outputs that jurisdiction_key and timezone. Given phone metadata indicates a different country than the verified address, When resolving, Then the verified address still governs and confidence is high unless the address is unverified, in which case confidence is medium and conflict_summary=true. Rule: Quiet-hour checks for telehealth use the patient’s timezone from the resolution output.

Auditability and Traceability

Rule: Every resolution produces an immutable audit record containing: patient_id (hashed), timestamp, input signals and hashes, chosen jurisdiction_key, timezone, confidence, reason_codes, cache_status, and tzdb_version. Rule: Audit records are queryable by time range and patient_id hash and retained for at least 24 months. Rule: A sampling endpoint returns resolution distributions by jurisdiction and confidence to support compliance monitoring.

Rule Library & Versioning

"As a compliance officer, I want a maintained, versioned library of TCPA and regional rules applied automatically so that the practice stays compliant as laws change."

Description

Maintain a centralized, versioned library of TCPA and regional regulations covering quiet hours, consent classes (informational/transactional vs marketing), channel constraints (SMS/email/voice), frequency caps, and required disclosures by jurisdiction. Rules are modeled as declarative policies with effective dates and precedence, enabling hotfix updates without code changes. The service provides a deterministic evaluator that resolves the active rule set given a jurisdiction, channel, purpose, and timestamp. It logs the rule version hash used per decision for traceability and supports staged rollouts (preview/test) before enforcement. Expected outcome: current, authoritative rules applied consistently across all sends with auditable provenance.

Acceptance Criteria

Deterministic Rule Evaluation for Send Decision

Given a jurisdiction code, channel in {SMS, Email, Voice}, purpose in {Informational, Marketing}, and a UTC timestamp When the evaluator is invoked with these inputs Then it returns exactly one decision containing: outcome in {ALLOW, DEFER, BLOCK}, defer_until (nullable), required_disclosures[], consent_class, frequency_cap_remaining, policy_set_id, policy_version_hash, evaluation_id And repeated invocations with identical inputs return the same outcome and policy_version_hash And the evaluator responds within p95 <= 150 ms at 200 RPS sustained load

Quiet Hours Enforcement in Patient Local Time

Given a patient location resolvable to a time zone and jurisdictional quiet hours window When the evaluator processes a UTC timestamp Then it converts to the patient’s local time and if within quiet hours sets outcome=DEFER and defer_until to the next permissible local time boundary And daylight saving transitions are honored so no message is sent during defined local quiet hours And defer_until is computed to the minute with no early sends across all supported channels

Consent Class and Channel Constraints Enforcement

Given purpose=Marketing and channel=SMS with no valid SMS marketing opt-in per jurisdiction When the evaluator runs Then it returns outcome=BLOCK and includes reason "consent_missing" and no required_disclosures Given purpose=Informational and channel=SMS where transactional messaging is permitted When the evaluator runs Then it returns outcome=ALLOW and includes required_disclosures per jurisdiction And per-channel, per-purpose frequency caps are enforced; when the cap is exceeded within the defined rolling window the outcome=BLOCK with reason "frequency_cap_exceeded"

Jurisdiction Precedence and Fallback

Given policies exist at Global, Country, State/Province, and Local levels with defined precedence Local > State > Country > Global When multiple policies are applicable for the same inputs and timestamp Then the evaluator selects the highest-precedence policy whose effective date range includes the timestamp And if no applicable policy exists at any level, the evaluator fails safe with outcome=BLOCK and reason "no_applicable_rule" And if the highest-precedence policy is not yet effective, the next lower-precedence active policy is used

Rule Library Versioning and Hotfix Activation

Given an authorized admin uploads a new policy version (policy_set_id, version_hash, effective_from, precedence) via API When the version is activated Then new decisions use this version within 10 minutes without service restart or code deployment And prior versions remain retrievable via API by version_hash And policy versions are immutable; attempts to modify an existing version are rejected with a validation error

Staged Rollouts with Preview/Test Mode

Given a candidate policy version is set to preview When the evaluator runs Then it computes both current and candidate outcomes and records a diff linked to evaluation_id without changing the enforced outcome And preview telemetry (match rate, allow/block/defer deltas, top rule differences) is queryable via API for a time range And promoting the candidate switches enforcement to that version; rollback to the prior version is possible via a single API call

Decision Logging and Auditability

Given any evaluation completes When the decision is logged Then the record includes evaluation_id, policy_set_id, policy_version_hash, jurisdiction, channel, purpose, input timestamp, outcome, reasons, defer_until, required_disclosures, consent_snapshot_id And decision logs are retained for 7 years and are immutable And an audit API can retrieve a decision by evaluation_id or message_id with p95 latency <= 2 seconds And a verification endpoint returns a SHA-256 digest of the policy document matching the policy_version_hash

Consent Matrix & Double Opt-In

"As a patient intake coordinator, I want the system to track and enforce consent by channel and purpose, including double opt-in where required, so that only permitted messages are sent."

Description

Model, capture, and enforce consent by channel (SMS, email, voice) and purpose (informational vs marketing) at the patient level, including jurisdiction-specific requirements for double opt-in and opt-out keywords. Ingest consent from intake forms, inbound messages (e.g., STOP/UNSUBSCRIBE), and EHR/PM integrations; timestamp and store consent provenance. Provide automatic downgrading of messages to informational when marketing consent is absent and suppression when no lawful basis exists. Sync consent state to the send pipeline in real time and reconcile discrepancies with external systems. Expected outcome: only permitted communications are delivered, with clear evidence of consent or lawful basis per message.

Acceptance Criteria

SMS Double Opt-In Enforcement by Jurisdiction

Given a patient’s location resolves to a jurisdiction requiring double opt-in for SMS marketing And the patient has not previously confirmed SMS marketing opt-in When the practice attempts to enroll the patient in any SMS marketing campaign Then the system sends a single confirmation-request SMS using the jurisdiction-approved template outside restricted quiet hours And blocks all SMS marketing sends until a valid confirmation keyword is received And upon receiving a valid confirmation keyword within 30 days, the system marks SMS marketing consent as Granted with timestamp and source And upon receiving an opt-out keyword or receiving no confirmation within 30 days, the system marks SMS marketing consent as Denied and suppresses marketing SMS And all actions are logged with the jurisdiction rule version applied

Opt-Out Keywords Suppress Further Sends

Given any inbound message on SMS, email, or voice that matches the jurisdiction-specific opt-out keywords for that channel and purpose When the message is received Then the system updates the patient’s consent state to Revoked for the matching channel and purpose with timestamp and source=Inbound And suppresses all further messages for that channel and purpose within 60 seconds across all campaigns and automations And sends a one-time opt-out confirmation where permitted by jurisdiction; otherwise no confirmation is sent And logs the event and the suppression reason in the audit trail

Intake Form Consent Capture with Timestamped Provenance

Given a patient completes a SmileCue intake form selecting consent checkboxes per channel (SMS, email, voice) and purpose (informational, marketing) When the form is submitted Then the system records a separate consent event per selected channel and purpose with timestamp, IP, user agent, form ID and version, and location determination method And associates the events to the patient record and marks corresponding consent states as Granted And triggers any required double opt-in workflows per jurisdiction for channels/purposes that require confirmation And rejects submissions with ambiguous or partially completed consent fields, prompting the patient to review

EHR/PM Consent Import and Conflict Reconciliation

Given an EHR/PM integration provides consent indicators with timestamps per channel and purpose When imported consent conflicts with SmileCue’s current consent state Then the system reconciles by applying the event with the latest valid timestamp per channel and purpose; if timestamps are equal or missing, opt-out (revocation) takes precedence And records a reconciliation entry detailing source systems, timestamps compared, decision taken, and affected fields And emits a webhook and dashboard notification when a patient’s consent state changes due to reconciliation

Automatic Messaging Downgrade Without Marketing Consent

Given a marketing message is scheduled for a patient who lacks marketing consent but has informational consent for the same channel When the message is evaluated by the send pipeline Then the system automatically substitutes the configured informational template variant for that message and updates tracking to informational classification And if no informational variant exists, the system suppresses the send and records a suppression with reason=No Lawful Basis And no marketing content is delivered to the patient in either case

Real-Time Consent State Sync to Send Pipeline

Given any consent change event is persisted (e.g., opt-in, opt-out, downgrade, reconciliation) When the event is committed to the consent ledger Then the send pipeline reflects the new state within 5 seconds and re-evaluates all pending messages for the affected patient And cancels in-flight messages that are now prohibited and prevents any further prohibited sends And adds a pipeline action log entry linking the consent event to each canceled or allowed message

Per-Message Lawful Basis Evidence and Auditability

Given any message is delivered, downgraded, or suppressed When a user views the message detail in the communication log Then the system displays the evaluated lawful basis (e.g., explicit consent, treatment, implied) with channel, purpose, consent event ID, timestamp, source, and jurisdiction rule set/version applied at decision time And provides an exportable evidence bundle (PDF and CSV) containing the message content/metadata and the consent provenance records And ensures evidence records are immutable and include a cryptographic hash for tamper detection

Quiet Hours Enforcement & Rescheduling

"As an office manager, I want messages to be automatically paused and rescheduled outside quiet hours based on patient location so that we respect regulations and avoid complaints."

Description

Automatically enforce jurisdiction-specific quiet hours by evaluating the patient’s local time prior to send. If outside allowed hours, place the message into a deferred queue and reschedule to the earliest permissible window while preserving SmileCue’s branching logic and dependencies (e.g., confirmation windows). Support practice-defined stricter hours, emergency bypass for critical care notices, and volume smoothing at window openings to avoid carrier spam heuristics. Handle daylight saving transitions and leap day edge cases. Expected outcome: compliant timing of communications without manual calendar adjustments, reducing complaints and legal risk.

Acceptance Criteria

Defer and Reschedule Outside Quiet Hours

Given a message to a patient whose local time falls within quiet hours for the channel and jurisdiction When a send is attempted Then the system must not send the message And it must place the message into a deferred queue with reason "Quiet Hours" And it must reschedule the message to the earliest permissible time within the same calendar day if any sendable window remains, otherwise the next calendar day at the window opening And the planned send timestamp is updated in message metadata And no retries are attempted during quiet hours

Jurisdiction and Channel Quiet Hours Selection by Patient Location

Given a patient has a resolvable location and timezone and a message channel C When determining the permitted send window Then the system applies quiet hours defined for the patient's country and state/province for channel C And if country and state rules differ, the stricter (longer quiet-hours span) is applied And permitted window calculations use the patient's local timezone derived from their location

Practice-Defined Stricter Hours Override

Given a practice has configured quiet hours that are stricter than jurisdiction defaults for a channel When sending or rescheduling messages for that practice Then the system enforces the stricter practice-defined hours And if practice settings are looser than jurisdiction rules, jurisdiction rules prevail

Emergency Bypass for Critical Care Notices

Given a message is tagged Emergency and of consent class Informational And the patient's local time is within quiet hours When the message is queued Then the system bypasses quiet hours and sends immediately And the bypass event is recorded with reason "Emergency" And if the message is of consent class Marketing, bypass is not allowed and the message is deferred per quiet hours

Preserve Branching Logic and Time-Dependent Windows

Given a message belongs to a workflow branch with a deadline constraint (e.g., must be sent at least X hours before appointment) When a send is deferred due to quiet hours Then the rescheduled time must still satisfy the branch's temporal constraints and dependencies And if no permissible reschedule exists before the branch's expiry, the message is canceled with status "Expired" and the defined alternate branch is triggered And downstream nodes dependent on this message update their schedules accordingly

Volume Smoothing at Quiet-Hour Window Opening

Given N deferred messages for a practice and channel share the same window opening at time T0 When T0 is reached Then the system applies uniform random jitter of 0–600 seconds to the rescheduled messages And it enforces default per-practice per-channel throughput caps of SMS ≤ 30/minute, Email ≤ 120/minute, Voice ≤ 10/minute (configurable) And no patient's messages are sent less than 60 seconds apart on the same channel And the backlog of size ≤ cap*10 is fully dispatched within 10 minutes of T0

Daylight Saving and Leap Day Scheduling Integrity

Given a patient's timezone enters Daylight Saving Time (spring forward) and 02:00–02:59 local time does not exist When a message reschedules into the nonexistent hour Then it is moved to the earliest permissible minute at or after 03:00 local time, respecting quiet hours Given a patient's timezone exits Daylight Saving Time (fall back) and 01:00–01:59 repeats When a message is rescheduled into the repeated hour Then it is sent only once at the scheduled wall-clock time without duplication Given February 29 exists in the current year When a message is deferred across Feb 28–Mar 1 due to quiet hours Then rescheduling uses the correct calendar date, and messages targeted for Feb 29 are delivered on Feb 29 at the earliest permissible time

Compliance Pre-Check Guardrails

"As a hygienist, I want the system to pre-check each message and block or adjust content and format when it violates rules so that I don’t accidentally send non-compliant communications."

Description

Introduce a pre-send compliance validator that evaluates channel, content type, consent state, frequency caps, and jurisdictional rules before dispatch. The validator blocks sends that violate policy, downgrades marketing content to informational when allowed, injects mandated disclosures/opt-out language, and enforces channel-specific constraints (e.g., voice to mobile restrictions, SMS length and opt-out footer). Provide clear, actionable error/warning messages to staff and APIs, and expose override paths only where legally permitted (with justification capture). Expected outcome: prevention of non-compliant sends and consistent, explainable guardrails within existing workflows.

Acceptance Criteria

Block Sends Outside Jurisdiction Rules and Quiet Hours

Given a patient’s jurisdiction is resolved and local time falls within quiet hours And the message content is classified as marketing without the required consent level for that jurisdiction and channel When the system validates a pending send (SMS, email, or voice) Then the validator blocks the send And returns error code COM-001 with a human-readable message indicating the violated rule(s) And includes ruleRef(s) and jurisdictionId in the response payload And no message is queued or sent And an audit log entry is created capturing userId/apiKey, decision=blocked, ruleRef(s), timestamp, and requestId

Automatic Downgrade of Marketing to Informational When Allowed

Given a message is tagged as marketing And the jurisdiction rule set permits downgrading marketing to informational for this use case and channel And the recipient has valid informational consent When the system validates the send Then the validator changes classification from marketing to informational And injects all required informational disclosures/footers And allows the send to proceed And returns warning code COM-201 indicating downgrade occurred with ruleRef And records an audit entry with action=downgrade, originalClass, newClass, ruleRef, and timestamp

Mandated Disclosures and SMS Length Handling

Given channel=SMS and content is compliant for the jurisdiction And the jurisdiction requires an opt-out footer (e.g., "Reply STOP to opt out") When the validator appends mandated disclosures Then if total length fits within up to 3 concatenated segments for the detected encoding, the message is allowed with the footer appended And a warning COM-202 is returned indicating final segment count Then if total length would exceed 3 segments, the validator blocks the send And returns error COM-002 with guidance to shorten content or switch channel And no partial messages are sent

Voice Channel Mobile-Only Enforcement

Given channel=voice And the applicable jurisdiction restricts this content class to mobile numbers only And the target number is classified as non-mobile (e.g., landline/unknown) When the validator evaluates the send Then the validator blocks the send And returns error COM-003 with message "Voice to non-mobile prohibited in this jurisdiction for this content class" And suggests compliant alternatives (e.g., SMS or email) when available And logs the decision with ruleRef and numberType

Frequency Caps by Channel and Content Class

Given a recipient has received N messages via SMS for appointment-related content within the last 7 days And the jurisdiction/org-configured cap for this channel and content class is N per 7 days When another non-urgent message is validated Then the validator blocks the send or schedules it at the next eligible time if auto-reschedule is enabled And returns code COM-004 with nextEligibleSendAt and capDetails And no message is dispatched before the cap window resets And an audit entry records the cap violation with counts and window

Structured UI/API Validation Response

Given a send request is evaluated via UI or API (single or bulk) When validation completes Then the response contains overallDecision in {allow, allow_with_warnings, block} And includes arrays of codes, messages, and ruleRefs per recipient And contains overrideAllowed boolean and requiredJustificationFields when true And for bulk requests, each recipient has an independent decision object and no compliant recipient is blocked by others And the 95th percentile validation latency for single-recipient requests is ≤300ms under nominal load

Legally Permitted Overrides with Justification and Audit

Given a validation result is block and overrideAllowed=true per the applicable rule And the user holds the Compliance Override role/permission When the user submits an override with a justification reason and a free-text explanation of at least 20 characters Then the validator allows the send And records an immutable audit entry with userId, timestamp, ruleRef, decision=overridden_allow, justificationReason, justificationText, and sourceIp And the audit record is retrievable via API within 5 seconds When overrideAllowed=false, the UI/API does not present an override option and any attempt returns HTTP 403 with code COM-403

Immutable Compliance Audit Trail

"As a practice owner, I want detailed, exportable logs showing why a message was or was not sent, what rules applied, and what consent was on record so that I can respond to audits and disputes."

Description

Create an immutable, privacy-aware audit trail for all compliance decisions and message attempts. Each record stores the patient pseudonymous identifier, timestamp, jurisdiction and timezone used, consent snapshot and provenance, rule version hash, decision outcome (sent/suppressed/downgraded/deferred), disclosures applied, and quiet-hours reschedule data. Support tamper-evident storage, configurable retention aligned with HIPAA, PHI minimization/redaction, and export APIs for audits and legal inquiries. Provide filters and reports by jurisdiction, channel, and outcome. Expected outcome: defensible evidence for audits and disputes without exposing unnecessary PHI.

Acceptance Criteria

Record Completeness per Decision Event

Given a message attempt is evaluated for delivery When the system finalizes a compliance decision (sent | suppressed | downgraded | deferred) Then an audit record is persisted before any dispatch containing: pseudonymous_patient_id; utc_timestamp (ISO 8601, ms precision); jurisdiction (country/state code) and iana_timezone used; channel; consent_snapshot {class, status, scope, captured_at}; consent_provenance {source_system, method, record_id}; rule_version_hash (SHA-256 hex); decision_outcome; disclosures_applied {ids, content_hash}; quiet_hours {original_at, rescheduled_at, reason} when applicable; and a unique immutable record_id (UUIDv4) And the write succeeds with p95 latency <= 100 ms And if the write fails, the decision is not executed and the attempt is retried until persisted or marked failed with an error code

Tamper-Evident Append-Only Log

Given the audit store is configured When any actor attempts to update or delete an existing record prior to retention expiry Then the operation is rejected and recorded in a security audit log And each record includes record_hash = SHA-256(canonical_payload + previous_record_hash) enabling a hash chain And a verify-integrity operation over any range detects modification and identifies the first invalid link And a daily chain_anchor_hash is sealed to write-once storage, and verification can start from the nearest anchor

PHI Minimization and Pseudonymization

Given audit records are persisted Then no raw PHI fields are stored (full name, DOB, full phone/email, message body, free text) And patient references use pseudonymous_patient_id; channel addresses are masked (e.g., phone last4, email local-part hashed) when stored And disclosures_applied stores IDs and content_hash, not full text And export APIs default to redacted output (include_phi=false) and require audit.read.phi scope to request minimally expanded fields

Configurable Retention and Legal Hold

Given a retention policy is set to N years When records exceed N years Then they are purged within 24 hours, leaving a cryptographic tombstone preserving chain integrity and purge metadata {purged_at, reason} And when a legal hold is applied to a patient, jurisdiction, or date range Then matching records are excluded from purge and marked with legal_hold_id and applied_at And retention changes apply prospectively and are auditable

Export API with Filters and Pagination

Given an authorized user with scope audit.read requests an export with filters {date_from, date_to, jurisdiction, channel, outcome} When the request is valid Then the API returns 200 with results filtered accordingly in the requested format (JSON or CSV), sorted by utc_timestamp ascending, with pagination (page_size up to 10000) and a next_cursor when more data exists And requests over 1000000 records are processed asynchronously, returning a job_id and completion webhook or polling endpoint within 2 seconds And the API enforces rate limits (e.g., 60 req/min per tenant) and returns 429 with Retry-After when exceeded And all export requests and deliveries are themselves logged in the audit trail with requester_id and purpose

Aggregated Reports by Jurisdiction, Channel, Outcome

Given a reporting request with filters {date_range, jurisdictions[], channels[], outcomes[]} When the report is generated Then the system returns counts grouped by jurisdiction, channel, and outcome with totals, and an optional daily breakdown in a specified timezone And reported counts reconcile exactly with the raw audit records for the same filters And report generation completes within 10 seconds for up to 30 days of data

Quiet Hours Reschedule Traceability

Given a send falls within a jurisdiction's quiet hours When the system defers the message Then the audit record captures quiet_hours {window_start, window_end, rule_timezone, reason="quiet_hours"} plus original_scheduled_at and rescheduled_for And upon actual dispatch, a subsequent record links back via prior_decision_id and records decision_outcome="sent" with the same rule_version_hash and jurisdiction snapshot And if consent changes before rescheduled_for, the new decision outcome and consent_snapshot are recorded with linkage to the original deferral

Evidence Vault

Generates immutable, audit-ready evidence packs for each consent event, including timestamp, channel, language, template version, user/source, and IP/caller ID where applicable. One-click export with role-based access lets compliance leads respond to audits or carrier inquiries in minutes instead of days.

Requirements

Tamper-Evident Consent Ledger

"As a compliance lead, I want each consent event recorded in a tamper‑evident ledger so that I can prove integrity and non‑repudiation during audits."

Description

Implement an append-only, cryptographically verifiable ledger to record every consent event with required metadata (timestamp, channel, language, template version, user/source, IP/caller ID). Entries are chained via hashes with periodic anchors (e.g., daily Merkle root) and stored on immutable, retention-enforced storage (e.g., WORM/S3 Object Lock). Each event receives a globally unique Consent Event ID. Data is encrypted at rest and in transit, with managed keys and rotation. Provide a verification service to validate event integrity against the anchored hashes. Integrate with SmileCue’s consent capture flows across SMS, email, and voice so ledger writes are synchronous and resilient with idempotency. Support retention policies aligned with HIPAA and business rules, high availability, and backfill/migration for legacy consent events. Outcome: defensible, non-repudiable records ready for audit.

Acceptance Criteria

Required Metadata and Consent Event ID

Given a consent is captured via SMS, email, or voice When the ledger write is attempted Then the record must include: ConsentEventID (globally unique, time-sortable), serverTimestamp (UTC ISO 8601), channel ∈ {sms,email,voice}, language (BCP 47), templateVersion (semver), userOrSource, tenantId, and networkIdentifier appropriate to channel (IP for web/email, callerId for voice when available) And the write is rejected with a 4xx and no append occurs if any required field is missing or malformed And upon successful write the read API returns the exact persisted metadata for that ConsentEventID And across 1,000,000 generated events there are zero duplicate ConsentEventIDs

Append-Only Immutability Enforcement

Given an existing ledger record When a client attempts to update or delete it via any API or admin tool Then the operation is blocked (HTTP 405/409) and no stored bytes are altered And a correction can only be recorded by appending a new compensating record that references the original ConsentEventID And audit logs capture the blocked mutation attempt with actor, timestamp, and reason

Synchronous Write and Idempotency Across Channels

Given a user provides consent in SmileCue via SMS link, email link, or IVR When the consent is submitted Then the application only marks the consent as captured after the ledger confirms a committed append And end-to-end additional latency introduced by the ledger commit is ≤ 300 ms at p95 under 200 requests/minute per tenant And if the client retries with the same Idempotency-Key within 24 hours Then the ledger returns the original ConsentEventID and does not create a duplicate entry And concurrent duplicate submissions (race within 1 second) yield a single persisted record And on transient failures the system retries with exponential backoff up to 3 times before surfacing an error, ensuring no partial writes

Hash Chain Integrity and Daily Merkle Anchoring

Given a sequence of events within a day When each event is written Then its hash includes the previous event hash and the record payload, producing a verifiable chain And by 00:10 UTC next day the system publishes and stores the daily Merkle root for all events from that UTC day Given a ConsentEventID When the verification service is called Then it returns Verified with the proof path and daily anchor hash if the record is intact And returns Tampered with mismatch details if any byte differs from the anchored hash And recomputing the Merkle root from raw events matches the stored anchor exactly

Immutable WORM Storage with Retention Enforcement

Given ledger data objects are written to storage with Object Lock (Compliance mode) When a user without Compliance role attempts to delete or shorten retention before the retentionUntil date Then the operation fails and no bytes are removed or altered And retention policies are configurable per tenant (default 6 years; cannot be reduced below minimum) And legal hold can be enabled/disabled only by Compliance role and is fully audited And storage metadata exposes retentionUntil and legalHold state for each object

Encryption and Managed Key Rotation

Given ledger data at rest Then it is encrypted with a managed KMS CMK (AES-256) and access is limited to approved service roles And KMS key rotation occurs at least annually without downtime and without loss of decryptability for historical records Given any client/service connects to the ledger or verification API When using TLS Then only TLS 1.2+ with modern ciphers is accepted and lower versions are rejected And key usage (encrypt/decrypt) and admin actions are logged and exportable for audit

Legacy Consent Backfill and Migration

Given legacy consent records exist outside the ledger When the backfill job runs Then each legacy record is mapped to required metadata, marked origin=legacy, assigned a ConsentEventID, appended to the ledger, and included in the day’s Merkle root And the job is idempotent: reruns produce no duplicate ledger entries (same idempotency key → same ConsentEventID) And throughput is ≥ 10,000 events/hour with ≥ 99.9% success rate, producing a completion report with counts and failures And a random 1% sample verified via the verification service returns Verified

One-Click Evidence Pack Export

"As a compliance lead, I want to export a complete evidence pack with one click so that I can respond to auditor requests within minutes."

Description

Generate an audit-ready evidence pack for any consent event with a single action. The pack includes a human-readable summary and a machine-readable JSON bundle containing: consent text snapshot (rendered message), language/locale, template version, timestamp, channel, user/source, IP/caller ID, hash-chain proofs, delivery receipts, patient responses/branching transcript, and policy/version references. Export formats: PDF (watermarked, paginated, sealed with timestamp) and JSON (schema-versioned). Include a QR/code link to a verification endpoint to validate integrity. Support batch export for multiple events, and allow inclusion/exclusion of PHI per role policy. Integrate with RBAC and audit logging; all exports are recorded with user, time, and reason codes. Outcome: rapid, consistent auditor-ready documentation.

Acceptance Criteria

Single Event One-Click Export Generates Complete Pack

Given a user with Export Evidence permission views a consent event When they click "Export Evidence Pack" Then two files are generated: a watermarked, paginated PDF sealed with a UTC timestamp and a schema-versioned JSON bundle And the pack includes: consent text snapshot (rendered message), language/locale, template version, event timestamp (ISO 8601, UTC), channel, initiating user/source, IP address and/or caller ID (where applicable), hash-chain proofs, delivery receipts, patient responses and branching transcript, and policy/version references And the PDF contains a scannable QR code and short code link to the verification endpoint And the JSON bundle includes a schemaVersion field and validates against the current published schema And the export completes within 3 seconds at p95 for a single event ≤ 2 MB

Role-Based PHI Inclusion/Exclusion Controls

Given RBAC policies define that Compliance Leads may include PHI and Front Desk users may not When a Compliance Lead exports an evidence pack Then the UI presents an "Include PHI" toggle (default Off) And enabling the toggle includes PHI fields; disabling redacts PHI fields (e.g., name, DOB, phone, email, MRN) with clear redaction markers in both PDF and JSON When a Front Desk user exports Then the "Include PHI" control is hidden or disabled and PHI is always excluded And the export metadata records whether PHI was included And automated tests verify no PHI tokens appear in outputs when PHI is excluded

Batch Export for Multiple Consent Events

Given a user selects 10–500 consent events across patients and channels When they choose "Export Evidence Pack (Batch)" Then the system generates a ZIP containing per-event files {eventId}.pdf and {eventId}.json and a manifest.json And the manifest lists eventId, file checksums (SHA-256), schemaVersion, PHI inclusion flag, start/end timestamps, and success/error status per event And per-event failures do not abort the batch; failures are captured with error codes and messages in the manifest And the batch completes within 2 minutes at p95 for 500 events with average pack size ≤ 2 MB And all processed events (success and failure) are written to the audit log with the selected reason code

Export Audit Logging with Reason Codes

Given export reason codes are configured (Audit, Carrier Inquiry, Legal, Other + free text) When any export (single or batch) is initiated Then the user must select a reason code (and provide notes if Other) And an immutable audit log entry is created containing: exportId, userId, role, timestamp (UTC), source IP, reason code and notes, eventIds, PHI inclusion flag, item counts, and outcome (success/failure) And admins can retrieve the audit record by exportId via UI and API And attempts without a reason code are blocked with a validation error and no files are generated

Verification Endpoint and Tamper Detection via QR/Link

Given a verifier scans the PDF QR code or opens the printed short link When the verification endpoint is requested with the pack’s token Then the service returns integrity status (Valid/Invalid), eventId, pack timestamp, and a hash that matches the embedded hash-chain proofs And if the PDF or JSON has been altered, the status is Invalid with a specific reason code (e.g., HASH_MISMATCH) And the verification response never returns PHI And the endpoint meets p95 latency < 500 ms and monthly availability ≥ 99.9%

Multichannel Multilingual Fidelity in Evidence Pack

Given consent events were sent via SMS, Email, and Voice/IVR in English and Spanish When an evidence pack is exported Then the PDF renders the consent text snapshot exactly as sent (including line breaks, emojis, and directionality), and shows channel, template version, and language/locale (BCP 47) And the JSON includes channel, templateVersion, language/locale, and delivery artifacts And SMS entries include carrier delivery receipts when available; Email includes provider delivery status; Voice includes caller ID and call SID; missing receipts are marked Not Available with provider reason And special characters are preserved in both PDF and JSON without substitution

Unauthorized Export Attempts Are Prevented

Given a user without Export Evidence permission attempts to export (UI or API) When they submit an export request (single or batch) Then the request is denied with HTTP 403 and a user-facing message indicating insufficient permissions And no PDF/JSON files are generated and no download links are created And the denial is recorded in the audit log with userId, time, IP, and denial reason

Role-Based Access & Least-Privilege Controls

"As a practice owner, I want role-based controls on evidence access so that only authorized users can view or export sensitive records."

Description

Introduce RBAC tailored to the Evidence Vault with predefined roles (e.g., Compliance Admin, Staff Viewer, External Auditor—Read Only) and granular permissions for view, export, share, and redact. Enforce MFA and support organization SSO/SAML/SCIM for user lifecycle. Scope access by location/provider and patient to minimize PHI exposure. Provide admin UI and APIs to assign roles, define approval workflows for external sharing, and apply policy-based redactions by role. Integrate with existing SmileCue org/tenant model and propagate permissions to export and share flows. Outcome: controlled, auditable access aligned with HIPAA minimum necessary standard.

Acceptance Criteria

Compliance Admin Assigns Roles via Admin UI

- Given an org tenant with predefined roles, when a Compliance Admin assigns the "Staff Viewer" role to user U with scope Location=A and Provider=X in the Admin UI, then U can access Evidence Vault with view-only permissions limited to that scope within 60 seconds. - Given role assignment or removal occurs, when the change is saved, then an immutable audit log entry is recorded with orgId, actorId, targetUserId, roles added/removed, scopes, timestamp (UTC), and source IP. - Given a user has no explicit permission for an action, when they attempt view/export/share/redact, then the system enforces least-privilege (deny by default), returns 403, and logs the attempt. - Given a Compliance Admin removes all roles from U, when U attempts to access Evidence Vault, then access is blocked and any active session is revoked within 1 minute.

Scoped Access by Location/Provider/Patient

- Given user U has Staff Viewer role scoped to Location=A only, when U lists or searches Evidence Vault items, then only evidence for Location=A is returned and counts exclude out-of-scope items. - Given U attempts to open an out-of-scope evidence record via direct URL or API ID, when the record belongs to Location≠A or a different provider/patient scope, then the response is 404 Not Found and an access-denied audit event is recorded. - Given U is additionally scoped to a patient list [P1, P2], when U queries Evidence Vault, then only evidence for P1 and P2 at Location=A is visible; all others are hidden.

External Auditor Read-Only with Time-Bound Access

- Given a Compliance Admin creates an External Auditor invitation with scope (locations/providers/date range) and expiry T, when the auditor accepts the invite and completes authentication, then the auditor can view only in-scope evidence and cannot export, share, or redact (UI controls hidden; API returns 403 for those endpoints). - Given the invitation expires at T, when the auditor attempts access after T, then access is revoked (401/expired) and the event is logged. - Given the Compliance Admin revokes the invitation prior to T, when the auditor attempts to use the link, then access is immediately invalid (410 Gone) and an audit entry is recorded.

MFA Enforcement and Sensitive-Action Step-Up

- Given any user attempts to access Evidence Vault and is not enrolled in MFA, when they sign in, then the system requires MFA enrollment (TOTP primary; SMS fallback if enabled by org policy) before granting access. - Given a user with permission initiates export, redact, or external share, when the user has not completed MFA within the last 5 minutes, then a step-up MFA challenge is required and failure denies the action. - Given org policy disables SMS fallback, when a user attempts to enroll via SMS, then the option is unavailable and only approved methods are offered.

SSO/SAML Authentication and SCIM Lifecycle

- Given SAML SSO is configured, when a user authenticates via the IdP, then SmileCue establishes a session mapped to the correct org/tenant and applies Just-In-Time role/scoping mappings from SAML attributes if configured; otherwise the user has no roles (no access). - Given SCIM creates/updates user U with roles and scopes, when the SCIM call succeeds (2xx), then the changes take effect within 5 minutes and are reflected in the Admin UI and permission checks. - Given SCIM deprovisions user U, when the deprovision call succeeds, then new logins are blocked immediately and existing sessions lose Evidence Vault access within 5 minutes; attempts are logged as deprovisioned.

Policy-Based Redaction by Role Across UI, API, and Exports

- Given a role lacks permission view_full_phi, when viewing evidence details, then PHI fields (e.g., phone numbers masked to last 4, IP/caller ID hidden or tokenized) are redacted per policy version V. - Given an export (CSV/PDF/JSON) is generated by a user without view_full_phi, when the file is produced, then the same redactions are applied and the export includes a redaction manifest noting fields redacted and policy version V. - Given a share link is created for a recipient role lacking view_full_phi, when the recipient accesses the data, then redactions are enforced server-side and are non-reversible because underlying values are omitted from payloads. - Given policies are updated to V+1, when a user requests data thereafter, then redactions reflect V+1 and the audit log records policy version applied.

Permission Propagation to Export/Share with Approval Workflow

- Given a user with share permission initiates an external share for a defined scope, when org policy requires 1 Compliance Admin approval, then the request enters Pending and no link is issued until approval is granted. - Given an approver approves the request, when approval is recorded, then a time-bound, scope-limited link is generated with enforced redaction based on recipient role, watermarking (org, requester, timestamp), and all events are audited. - Given the request is rejected or expires before approval, when the requester checks status, then the request is closed with no link ever created and the outcome is logged. - Given an approved link is revoked by an admin, when a recipient attempts to access it, then the link is invalid within 1 minute and returns 410 Gone; revocation is logged.

Comprehensive Access and Export Audit Logging

"As a security officer, I want detailed access logs for the Evidence Vault so that I can demonstrate compliance and detect misuse."

Description

Capture immutable logs for all Evidence Vault interactions, including searches, views, exports, shares, downloads, and revocations with actor identity, timestamp, IP/device, reason code, and target resource. Store logs in append-only storage with retention and tamper-evidence. Provide filtering, reporting, and export to CSV/JSON. Emit webhook/SIEM integrations for real-time monitoring and anomaly detection (e.g., unusual export volume). Include auditor-ready reports summarizing access over a time window per patient, user, or practice. Outcome: complete traceability to demonstrate compliance and detect misuse.

Acceptance Criteria

Immutable Logging of Evidence Vault Interactions

Given an authenticated actor performs search, view, export, share, download, and revocation on Evidence Vault resources When each action completes (success or failure) Then one audit event per action is persisted containing: event_id (UUIDv4), action_type, actor_user_id, actor_role, actor_practice_id, timestamp (UTC ISO-8601 with ms), ip_address or caller_id, user_agent/device_id (if available), reason_code (required for view/export/share/download/revoke), target_resource_type, target_resource_id, patient_id, consent_id, channel, template_version, request_id, outcome, and error_code (if any) And the event is queryable within 5 seconds of action completion (p95) And API-initiated actions include client_id and service principal identity in actor context And voice events include caller_id; SMS/Email include originating_ip when available And revocation events reference the prior share/export event_id

Append-Only Tamper-Evident Storage and Retention

Given the audit log datastore is operational When events are written Then events are append-only with no update/delete capability via UI/API And any attempt to modify/delete is blocked and produces a blocked_tamper_attempt audit event with actor identity and reason "immutable" And each event includes hash and prev_hash forming a verifiable chain; daily verification scans 100% of events and reports mismatches=0 And retention is configurable per practice (default 7 years, minimum 6); post-retention purge uses append-only tombstones preserving chain verifiability And storage maintains at least 3 replicas across 2 fault domains; recovery time objective <= 1 hour for audit data

Reason Code Enforcement for Sensitive Actions

Given a user initiates view, export, share, download, or revoke of an evidence pack When the request is submitted via UI or API Then reason_code is mandatory and must match an admin-managed allowlist; optional free-text note <= 500 chars may be provided And requests missing/invalid reason_code are rejected (HTTP 400/UI validation) and no target action occurs And both reason_code and note are persisted in the corresponding audit event And the UI clearly displays the captured reason on subsequent audit event views

Audit Log Filtering and Search Performance

Given a compliance user opens the Audit Log UI When filters are applied by time range, action_type, actor_user_id, actor_role, practice_id, patient_id, target_resource_id, channel, outcome, and reason_code Then the result set contains only matching events and displays total_count and unique_actor_count And sorting by timestamp (asc/desc) and by actor_user_id is supported; results are stable across pages (cursor-based pagination) And for up to 1,000,000 matching events, first page latency <= 3s p95 and subsequent pages <= 2s p95 And the UI renders a volume-over-time sparkline for the selected window

Audit Log Export to CSV and JSON

Given a permitted user selects Export for the current filtered audit log When CSV is chosen Then the file includes header row and one row per event with exactly the visible columns plus mandatory event_id,timestamp,action_type; values match on-screen data When JSON is chosen Then the file is a newline-delimited JSON stream of full event objects And the export metadata includes export_time_utc, filter_summary, total_rows, and SHA-256 checksum; checksum is displayed and stored And exports up to 5,000,000 events begin streaming within 10s and complete without server timeouts; partial exports are resumable via download tokens And the export action is itself audited with download_url (time-limited) and requestor identity

Real-Time Webhook/SIEM Streaming and Anomaly Detection

Given at least one webhook/SIEM destination is configured and active When an audit event is created Then a notification is delivered within 10 seconds p95, signed with HMAC-SHA256, including idempotency key; non-2xx responses are retried with exponential backoff for 24h And payload conforms to published JSON schema; optional syslog RFC5424 formatting is available for SIEM And anomaly detection evaluates per-actor and per-practice hourly export counts; if current hour > 3x 30-day moving average or > 200 exports, an anomaly_export_volume alert is generated, delivered to configured channels, and audited And alerts support acknowledge/resolve; all alert lifecycle changes are audited

Auditor-Ready Access Summary Reports

Given an auditor requests a summary for a defined window and scope (patient, user, or practice) When a compliance user generates the report Then the report includes totals, breakdown by action_type, unique actors, top 10 actors, timeline histogram, and an appendix listing event_ids with links And the report is produced within 60 seconds for up to 100,000 events and is available as PDF and CSV; report_id, generation_time_utc, filters, and integrity hash/signature are embedded And access to generate/download reports is restricted to Compliance Lead and Practice Admin; unauthorized attempts are blocked and audited

Secure Time-Bound Share Links for Auditors/Carriers

"As a compliance lead, I want to share an evidence pack securely with a carrier or auditor so that they can review it without creating an account or accessing other data."

Description

Enable generation of signed, revocable share links to specific evidence packs for external reviewers. Configurable expiration, single/multi-use tokens, optional IP allowlists, and maximum download/view limits. Support identity challenge (email OTP or delegated SSO) and watermarking with recipient info and timestamp. Provide a read-only web viewer with redaction modes to suppress non-essential PHI while preserving evidentiary value. All accesses are logged; links can be paused or revoked at any time. Integrate with email delivery for invitations and with RBAC for approval workflows. Outcome: fast, secure external review without provisioning full accounts.

Acceptance Criteria

Signed, Configurable Share Link Creation for a Single Evidence Pack

Given an internal user with ShareLink.Create permission and a target evidence pack ID When they configure expiration T, usage mode (single- or multi-use), view_limit V, and download_limit D, and click Generate Then the system creates a signed URL scoped only to that evidence pack with the configured constraints persisted And the link metadata includes issuer user ID, role, creation timestamp (UTC), expiration timestamp, token ID, and cryptographic signature And accessing any other evidence ID with the link returns 403 with reason "scope_mismatch" And when the view or download counts reach their limits, subsequent attempts return 403 with reason "limit_exceeded" And when the current time exceeds expiration, attempts return 410 with reason "expired" And the link appears in the pack’s Share Links list with status Active and accurate counters

Identity Challenge via Email OTP or Delegated SSO

Given a generated link requiring identity challenge via email OTP When the recipient enters the designated email and requests a code Then a 6-digit OTP is sent to that address and the OTP expires in 10 minutes And after 5 consecutive incorrect OTP attempts, the link is locked for 15 minutes and an audit event is recorded Given a link configured for delegated SSO (SAML/OIDC) to org X When the recipient authenticates successfully with org X Then access is granted and the asserted identifier (email/nameID) is bound to the session And all successful identity challenges record recipient identifier, method (OTP/SSO), timestamp, and IP in the audit log

Optional IP Allowlists and Network Enforcement

Given a link with an IP allowlist of one or more IPv4/IPv6 CIDR ranges When a request originates from an IP not in the allowlist Then access is denied with 403 and reason "ip_blocked" and a non-disclosing error page is shown And all denied and allowed attempts log source IP, matched rule decision, token ID, and outcome Given no allowlist is configured When the link is accessed from any IP Then evaluation passes and other controls apply

Read-Only Web Viewer with Redaction Modes

Given an external reviewer with valid access When they open the viewer Then the evidence pack renders in read-only mode with edit/delete actions disabled And a Redaction toggle presents at least two modes: Minimal PHI and Maximum PHI Suppression And switching modes updates the view within 1 second and shows a persistent banner of the active mode And redaction masks non-essential PHI while preserving consent text, timestamps, channel, template version, and identifiers needed for audit And copied text and printed/exported views reflect the currently active redaction mode

Watermarking of Views and Exports

Given reviewer identity is established for the session When the pack is viewed or exported Then a visible watermark shows recipient identifier (email/SSO ID), current timestamp (UTC), token ID, and "SmileCue Evidence Vault" on all pages And the watermark appears on-screen and in downloaded PDFs/images with consistent placement and 10–20% opacity And export actions are disabled until identity is bound; anonymous export is not permitted And the watermark persists after rasterizing the downloaded document to 300 DPI and re-inspecting

Pause/Revocation and Real-Time Access Control

Given an active link When an internal user pauses it Then new access attempts are denied with 403 reason "paused" within 60 seconds and existing sessions terminate on next request within 60 seconds When the link is revoked Then the token becomes unusable immediately, counters stop incrementing, and status shows Revoked And all pause/revoke events are recorded with actor, timestamp, reason, and previous state as append-only audit entries

Email Invitation Delivery and RBAC Approval Workflow

Given RBAC requires approval for external sharing When a creator submits a share link request Then an approver receives a workflow task and the link remains inaccessible until approved And only users with ShareLink.Approve can approve; approval captures approver ID, timestamp, and comments When approved Then an email invitation is sent to the recipient including the secure link, expiration date/time, and identity challenge instructions, with no PHI beyond patient initials and appointment date And delivery events (sent, bounced, opened) are recorded and visible in share link activity And if delivery fails permanently, the link remains inactive and the creator is notified

Template Snapshot & Localization Capture

"As a compliance analyst, I want the evidence to include the exact content the patient saw or heard so that I can prove the consent language matched our approved templates and the patient’s language."

Description

Capture and store the exact consent content presented at the time of consent, including language/locale, template version ID, merge-field resolutions, conditional branching taken, and rendering channel. For voice consents, store audio snippets or transcripts with timestamps; for SMS/email, store the original payload and a normalized, human-readable snapshot. Link snapshots to template change history and include them in evidence packs. Validate presence of snapshots at write time and flag any missing artifacts. Ensure proper encoding and storage to accurately reproduce content during audits. Outcome: verifiable proof that the patient saw or heard the approved consent language in the correct language.

Acceptance Criteria

SMS Consent Snapshot Capture

Given an approved consent template version exists in locale L and is sent via SMS with merge fields resolved for patient P When patient P responds with a valid affirmative keyword to grant consent Then the system stores the exact outbound SMS payload as sent and a normalized, human-readable snapshot with all merge fields resolved And the snapshot metadata includes: templateVersionId, locale, channel='SMS', consentEventId, patientId, sentTimestampUTC, receivedTimestampUTC, senderE164, recipientE164, providerMessageId And the snapshot is immutable and retrievable by consentEventId And retrieving the snapshot reproduces the exact text shown to the patient without re-evaluating the live template

Email Consent Snapshot Capture

Given an approved consent template version exists in locale L and is sent via Email with merge fields resolved for patient P When the consent email is delivered and patient P provides consent through the defined mechanism (e.g., reply or click capture is recorded) Then the system stores the original email payload (subject, from/to, body parts) and a normalized, human-readable snapshot with all merge fields resolved And the snapshot metadata includes: templateVersionId, locale, channel='Email', consentEventId, patientId, sentTimestampUTC, messageId And embedded links and placeholders in the snapshot reflect the exact resolved values at send time And the snapshot is immutable and retrievable by consentEventId

Voice Consent Audio/Transcript Capture

Given a voice consent flow using template version V is presented in language/locale L via phone call When the patient gives verbal consent during the call Then the system stores at least one of: (a) audio snippet(s) covering the consent language and the patient’s confirmation, or (b) a transcript with per-utterance timestamps And the snapshot metadata includes: templateVersionId, locale, channel='Voice', consentEventId, patientId, callStartTimestampUTC, callEndTimestampUTC, callerId, calleeId And if audio is stored, each snippet has start/end offsets; if a transcript is stored, each utterance has a timestamp And the snapshot is immutable and retrievable by consentEventId

Conditional Branch Path Recording

Given the consent template contains conditional branches that vary content based on patient/context data When the patient proceeds through the consent flow Then the system records the exact branch path taken, including branch identifiers and evaluation outcomes that led to each decision And the normalized snapshot contains only the content actually presented along that path And the recorded branch path is linked to the snapshot and visible in evidence retrieval

Template Version Linking to Change History

Given a consent snapshot is created for template version V When a user views the snapshot details Then the snapshot references templateVersionId=V and is linked to the template change history at version V And subsequent edits to the template create new versions without altering the existing snapshot And retrieving change history from the snapshot shows the diff/metadata applicable at version V

Audit Reproduction & Evidence Pack Inclusion

Given a compliance lead exports an evidence pack for a specific consent event When the pack is generated Then it includes the exact snapshot(s) tied to that event (SMS/email normalized snapshot and payload; voice audio/transcript), along with required metadata (locale, channel, templateVersionId, timestamps) And the textual snapshots are stored and rendered in a consistent encoding that preserves the original characters and directionality for the locale And opening the evidence pack reproduces the content exactly as presented/heard without contacting live template services

Write-Time Validation & Missing Artifact Flagging

Given the system attempts to persist a consent event When required snapshot artifacts for the channel are missing (e.g., no SMS/email payload + normalized snapshot, or neither audio nor transcript for voice) Then the write is rejected with a specific error code indicating missing artifacts And a compliance alert is logged with consentEventId and deficiency details And no consent record is marked as confirmed until required artifacts are present

Consent Pulse

Real-time dashboards and alerts that track opt-ins/opt-outs, consent decay, and carrier feedback. Automatically launches re-permission campaigns when consent nears expiration and suggests the best channel and language to recover opt-ins, keeping outreach compliant and lists healthy.

Requirements

Unified Consent Event Stream

"As an office manager, I want all consent activity consolidated per patient and channel so that outreach rules apply correctly and we have a single source of truth for compliance."

Description

Implement a real-time ingestion and normalization pipeline that consolidates consent events (opt-in, opt-out, revocation, double opt-in, consent purpose changes) from SMS, email, voice, web forms, and connected practice systems into a single patient profile. Maintain channel- and purpose-specific consent states with timestamps, provenance (source system, campaign, IP/device where applicable), and geolocation/time zone context for compliant outreach. Provide idempotent processing, de-duplication, and reconciliation logic to ensure a canonical consent record. Secure data with encryption in transit/at rest and role-based access controls aligned to HIPAA. Expose the unified consent state to SmileCue messaging, scheduling, segmentation, and reporting services via internal APIs and webhooks to enable downstream automation and accurate compliance checks.

Acceptance Criteria

Ingest and Normalize Consent Events From All Channels

Given valid consent events from SMS, email, voice, web forms, and connected practice systems with heterogeneous schemas When the pipeline ingests these events Then each event is normalized to the canonical schema with fields: patient_id, channel, consent_action (opt_in|opt_out|revoke|double_opt_in|purpose_change), consent_purpose, event_timestamp (UTC), provenance.source_system, provenance.campaign_id (nullable), provenance.ip (nullable), provenance.device_fingerprint (nullable), geo.country, geo.region, time_zone, validation_status=valid And normalized events are persisted to an append-only event store with acknowledgment from ≥2 replicas Given an event missing required fields or failing signature/CRC validation When processed Then it is rejected to a dead-letter queue with error_code and error_reason, and no state mutation occurs Given sustained load of 1000 events/minute When processed Then p95 end-to-end normalization latency ≤ 5 seconds and processing error rate ≤ 0.5% (excluding DLQ-intended rejects)

Maintain Channel- and Purpose-Specific Consent State

Given an existing patient consent state When a new consent_action for a specific channel and purpose is received Then the state is updated atomically with last_updated (UTC) and previous_state captured in audit metadata Given multiple events for the same patient/channel/purpose arrive out of order within 10 minutes When processed Then events are ordered by event_timestamp and applied deterministically using precedence: revoke > opt_out > opt_in > double_opt_in > purpose_change And only one final state mutation occurs Given a consent purpose_change event When applied Then the new purpose mapping is reflected in state and the prior purpose is retained in audit history Given consents subject to expiry policy When stored Then expiry_at is calculated and persisted And when current_time > expiry_at Then state transitions to expired and outreach checks return non-permissible

Idempotent Processing and De-duplication

Given duplicate deliveries of the same event (same idempotency_key or event_id+source_system) When processed multiple times Then only the first delivery mutates state and subsequent deliveries are recorded as duplicates without changing state Given retries due to transient failures When events are replayed Then processing remains idempotent and produces a single canonical state change in the audit trail Given a batch replay of historical events When processed Then de-duplication prevents double application while preserving chronological ordering Given system metrics When observed over 24 hours Then duplicate_detected_count and duplicate_block_rate are emitted and visible on the monitoring dashboard

Provenance and Audit Trail Completeness

Given any consent state change When persisted Then an immutable audit event is recorded with: event_id, patient_id, channel, consent_action, consent_purpose, event_timestamp (UTC), received_at, source_system, campaign_id (nullable), ip/device_fingerprint (nullable), sms_short_code or voice_call_sid (nullable), operator_user_id (nullable), geo, time_zone, and hash_chain Given an authorized compliance user queries audit for a patient over a date range ≤ 1000 events When executed Then results return within 3 seconds and include verification to detect tampering via hash_chain continuity Given any attempt to modify or delete an audit event When attempted Then the operation is blocked and a security event is logged with actor, action, timestamp, and reason

Security and HIPAA-Aligned Access Controls

Given PHI stored at rest When persisted Then AES-256 encryption is used with KMS-managed keys rotated at least every 90 days Given service-to-service communication When transmitting data Then TLS 1.2+ with mutual TLS is enforced and legacy ciphers are disabled Given a user with role Receptionist requests audit details When authorized Then access is denied (HTTP 403) and the attempt is logged; Given a user with role Compliance_Officer requests audit details When authorized Then access is granted and the access is logged with user, purpose, timestamp, and patient_id Given application and pipeline logs When generated Then PHI fields are redacted or tokenized and log access is restricted by role Given 5 failed access attempts within 10 minutes for an account When detected Then the account is temporarily locked and a security alert is issued

Expose Unified Consent via Internal APIs and Webhooks

Given an internal service requests consent state via GET /consents?patient_id=...&channel=...&purpose=... When the request includes a valid service token Then the API returns the canonical state with timestamps, provenance summary, and expiry_at with p95 latency ≤ 200 ms Given a consent state change is committed When webhooks are enabled for subscribers Then a signed (HMAC-SHA256) webhook is delivered within 3 seconds and retried with exponential backoff for up to 24 hours on failure Given duplicate webhook deliveries When received by subscribers Then each payload includes an idempotency_key to enable safe deduplication downstream Given an API request without valid authentication When processed Then the API returns 401 and no consent data is leaked

Reconciliation Across Channels and Providers

Given nightly reconciliation with carrier/ESP/voice provider suppression lists and connected practice systems When executed Then discrepancies in opt-in/opt-out/revocation states are identified, a reconciliation report is stored, and canonical state is corrected within 24 hours per policy Given conflicting states among systems When policy is applied Then precedence is: explicit patient opt-out in any channel > revocation > explicit opt-in with double opt-in > explicit opt-in > implicit/inferred, and the chosen resolution is recorded in audit Given reconciliation changes are made When completed Then downstream provider suppression lists are updated via APIs with confirmation; transient failures trigger retries with exponential backoff up to 48 hours Given reconciliation job failures When they occur Then on-call alerts are emitted with job_id, scope, error_summary, and next recommended action

Consent Decay Scoring & Thresholds

"As a compliance officer, I want visibility into when consent will become stale so that we can re-permission proactively and avoid non-compliant outreach."

Description

Create a rules-driven engine that calculates consent freshness for each patient by channel and purpose using regulatory guidance (e.g., TCPA/CTIA inactivity windows), carrier best practices, and configurable business policies. Compute decay scores and predicted expiration dates based on last interaction, engagement frequency, campaign type, and carrier feedback. Allow administrators to configure thresholds that trigger warnings and re-permission workflows, with support for practice- and location-level overrides. Handle special cases for transactional vs. marketing messages, quiet-hour constraints, and upcoming-appointment exemptions. Surface decay state to dashboards, alerts, and segmentation filters to proactively preserve list health.

Acceptance Criteria

Decay Score Computation by Channel & Purpose

Given a patient has consent records for SMS, Email, and Voice with purposes (marketing, transactional) And regulatory inactivity windows and business policy weights are configured When the decay engine runs for the patient Then a decay_score in [0,100] is produced per channel-purpose And the score incorporates last_interaction_at, engagement_frequency (configurable window), campaign_type, and latest carrier_feedback And identical inputs and configuration produce identical scores (idempotent) And missing non-critical inputs use configured defaults without failing processing

Predicted Expiration Date Calculation

Given a channel-purpose consent with a recorded last_interaction_at And an applicable inactivity window derived from regulatory/carrier rules and policy adjustments When the engine computes predicted_expiration_at Then predicted_expiration_at = last_interaction_at + applicable_window adjusted by configured engagement and carrier feedback modifiers And predicted_expiration_at is recalculated within 5 minutes of a new qualifying interaction And timestamps are stored and returned in ISO 8601 with patient timezone applied or clearly indicated

Admin Thresholds with Practice/Location Overrides

Given global thresholds (e.g., Healthy, Warning, At-Risk, Expired) are defined per channel-purpose And practice-level and location-level overrides may be configured When resolving thresholds for a patient at a specific location Then precedence is location override > practice override > global And any threshold change is versioned with actor, timestamp, scope (global/practice/location), and change details And crossing a threshold emits a single event per channel-purpose and updates consent_decay_state accordingly

Auto-Launch Re-Permission Workflows

Given a patient’s decay_score crosses a configured threshold or predicted_expiration_at is within a configurable X days window When evaluated by the engine Then a re-permission workflow is created once per patient per channel-purpose within a configurable suppression window And the recommended outreach channel and language are selected based on historical engagement, stated preferences, and carrier feedback constraints And no workflow is created if the patient is opted out for that channel, on a do-not-contact list, or has an active appointment-based exemption And each workflow launch is logged with correlation ID, triggering threshold, channel-purpose, and selected template

Transactional vs Marketing Handling & Appointment Exemptions

Given transactional and marketing consents are tracked separately When marketing consent decays or expires Then transactional messaging remains permitted where legally allowed and configured And if the patient has an upcoming appointment within a configurable N-day window and is not opted-out Then re-permission prompts are deferred until after the appointment window while transactional reminders continue And decay scoring proceeds but does not block transactional messages during the exemption

Quiet Hours & Timezone Compliance

Given quiet hours are configured per practice/location and carrier guidelines apply And the patient’s timezone is known or inferred When scheduling re-permission outreach Then messages are sent only within permitted hours in the patient’s local timezone And if outside permitted hours, outreach is queued for the next permitted window And time-critical transactional messages are exempt from quiet hours only if explicitly configured

Dashboards, Alerts, and Segmentation Surfacing

Given decay_score, predicted_expiration_at, and consent_decay_state are computed When users view dashboards Then aggregated counts by state and by channel-purpose are displayed with data freshness p95 ≤ 5 minutes And drilling into a segment reveals patient-level details including current values and last_updated_at And alerts are sent to configured channels when thresholds are crossed, containing counts, affected channel-purpose, and links to segments And segmentation supports filters by state, expires_within (days), channel-purpose, practice/location, and carrier feedback flags And the public API returns decay_score, predicted_expiration_at, consent_decay_state, and threshold metadata per channel-purpose

Auto Re-permission Campaign Orchestration

"As an office manager, I want re-permission to run automatically before consent expires so that our contact lists stay usable without manual outreach."

Description

Enable event-driven re-permission journeys that launch automatically as consent approaches configured decay thresholds. Provide pre-approved, compliant templates per channel with dynamic inclusion of required disclosures and opt-out instructions. Select the best channel, send time, and tone based on historical engagement, language preference, and carrier feedback, with safeguards for quiet hours, frequency caps, and PHI scrubbing. Support double opt-in where required, capture and reconcile new consent with full provenance, and gracefully handle STOP/HELP keywords. Include throttling, cohort-level A/B testing, and fallbacks across SMS, email, and voice. Write successful re-permissions back to the unified consent record and notify downstream systems via webhooks.

Acceptance Criteria

Event-Driven Launch at Consent Decay Thresholds

Given a patient consent record with a decay threshold configured (e.g., 30 days before expiration) And the patient is eligible based on jurisdictional rules and current consent status When the system detects the record crossing the threshold via real-time event or scheduled sweep Then a re-permission journey is automatically created within 60 seconds And the patient is enrolled into a cohort according to segmentation rules (e.g., channel eligibility, language, risk tier) And campaign throughput is throttled according to global and cohort rate limits (configurable) And no journey is launched for patients currently opted-out or with active legal holds

Compliant Templates with Dynamic Disclosures and Opt-Out

Given pre-approved templates exist for SMS, email, and voice in English and Spanish And regulatory disclosures and opt-out instructions are defined per channel and jurisdiction When a re-permission message is generated for an eligible patient Then the message uses a pre-approved template matching the patient’s preferred language And dynamically inserts required disclosures and opt-out instructions for the patient’s jurisdiction and carrier guidelines And includes practice identity and contact information And the rendered content passes compliance validation with zero errors prior to send

Adaptive Channel, Send Time, and Tone Selection with Safeguards

Given historical engagement data, carrier feedback, and language preferences are available And quiet hours and frequency caps are configured at global and practice levels When the system selects channel, send time, and tone for a patient’s journey step Then it chooses the highest-probability channel based on past engagement and carrier deliverability And schedules within the patient’s local timezone avoiding quiet hours And enforces frequency caps across all channels (e.g., per-day and per-week) And if the selected channel is disallowed by carrier feedback, the next best eligible channel is chosen

Double Opt-In Orchestration Where Required

Given a jurisdiction or carrier requires double opt-in for SMS And the patient is targeted via SMS in that jurisdiction When the first consent request is delivered Then the system waits for an affirmative keyword (e.g., YES) within the configured timeout window And upon receiving the keyword, sends a confirmation message containing disclosures and opt-out instructions And records both steps with timestamps, message IDs, and content hashes And if no affirmative response is received before timeout, the journey proceeds to configured fallback steps without marking consent as renewed

PHI Scrubbing and Content Safety

Given PHI scrubbing rules are configured (e.g., no diagnosis codes, no treatment details in outbound re-permission content) When any outbound content (SMS, email, voice transcript) is rendered Then the content is scanned and redacted according to rules prior to send And any message failing scrubbing is blocked, logged with reason, and retried with a safe template variant And audit logs capture pre/post-scrub checksums without storing raw PHI

Consent Capture, Reconciliation, and Keyword Handling

Given a patient responds with consent-related keywords (YES/STOP/HELP) or clicks consent links When the system receives the response via SMS, email, or voice IVR input Then the unified consent record is updated in real time with the new consent state, channel scope, timestamp, source message ID, and provenance (IP, user agent if web, carrier metadata if SMS) And STOP immediately updates opt-out across all applicable channels and halts active journeys And HELP returns a compliant assistance message without altering consent And conflicting signals within a 24-hour window are resolved per precedence rules with a full audit trail

Fallbacks, A/B Testing, Write-Back, and Webhooks

Given cohort-level A/B test variants are defined for templates, channel order, or send times And fallback rules across SMS→email→voice are configured When a journey executes for a patient Then the assigned variant is persisted and respected across all steps And on failure or non-response within SLA, the next fallback channel is attempted according to rules and caps And upon successful re-permission, the unified consent record is written with final state and provenance within 5 seconds And a webhook is delivered to registered downstream systems with a signed payload including consent state, scope, timestamps, and journey metadata; retries occur with exponential backoff until acknowledged

Carrier Feedback Ingestion & Block Alerts

"As a marketing coordinator, I want to know when carriers are filtering our messages and how to fix it so that re-permission and reminders reliably reach patients."

Description

Integrate carrier and aggregator delivery receipts, error codes, and 10DLC campaign status to classify filtering events, suspected spam blocks, and registration issues. Map error codes to actionable categories and recommended remediation steps (e.g., content changes, pacing adjustments, registration updates). Correlate feedback with consent decay, template content, and send patterns to identify root causes. Generate real-time alerts when thresholds are exceeded (per campaign, clinic, or channel) and surface a remediation checklist. Persist carrier insights in the consent record to inform channel selection and re-permission strategies.

Acceptance Criteria

Real-Time Carrier Feedback Ingestion and Normalization

Given a valid signed webhook from a carrier or aggregator containing a delivery receipt with provider_event_id, message_id, timestamp, and error code When the webhook is received Then the signature and IP allowlist are validated, the payload is normalized to the internal schema, and the event is stored within 60 seconds in 99% of cases Given duplicate webhook deliveries for the same provider_event_id When processed Then ingestion is idempotent and results in a single stored event with a deduplicated count incremented Given an invalid signature or malformed payload When received Then the event is rejected with HTTP 401 or 400 respectively, no data is persisted, and an error metric with reason code is recorded Given a delivery receipt referencing an unknown message_id When processed Then the event is placed in a reconciliation queue and is linked to the message record within 15 minutes if it arrives; otherwise it is marked Unreconciled with reason after 60 minutes Given multi-tenant traffic When events are stored Then data is partitioned by tenant (clinic) and channel, and no cross-tenant access is possible in queries or UI

Error Code Mapping to Actionable Categories and Remediation

Given a set of known carrier and aggregator error codes (e.g., 30007, 30006, 605) and 10DLC campaign statuses (e.g., Pending, Approved, Suspended, Rejected) When events are processed Then each is mapped to a normalized category from the taxonomy: Filtering suspected spam, Consent required/opt-out, Registration/10DLC issue, Number blocked/blacklisted, Throughput/rate limited, Destination unreachable, Content violation, Unknown Given an error code not present in the mapping When processed Then it is labeled Unknown, escalated to a review queue, and appears in the Mapping Coverage report; overall mapping coverage over the last 30 days is >= 95% Given a normalized category for an event When stored Then a remediation playbook is attached including 3–7 actionable steps specific to the provider and category Given a 10DLC campaign status webhook of Suspended or Rejected When ingested Then the campaign entity reflects the new status within 5 minutes and subsequent messages for that campaign are flagged Registration/10DLC issue with send blocked until status resolves

Correlation of Filtering with Consent Decay, Templates, and Send Patterns

Given delivery feedback from the last 14 days When the hourly correlation job runs Then per campaign and per clinic filtering rates are computed and correlated with consent age, template ID, send hour, and send velocity (messages per minute) Given any driver with a correlation score >= 0.30 and p-value < 0.05 When results are generated Then the top 3 drivers are surfaced with effect size, confidence, and example evidence (template IDs, time windows) Given a template with filtering rate >= 1.5x its campaign baseline and N>=200 sends When analyzed Then a root-cause card attributes elevated filtering to that template with relative risk and recommended actions Given a cohort with consents older than 12 months showing filtering rate >= 2x fresh consents When analyzed Then the system flags consent freshness as a likely driver and links to re-permission campaign setup

Threshold-Based Real-Time Alerts per Campaign, Clinic, and Channel

Given a configurable alert policy with default threshold filtering_rate > 5% and minimum volume N >= 200 in a 60-minute sliding window When any campaign, clinic, or channel breaches the threshold Then an incident is created within 2 minutes containing entity, window metrics, top suspected categories, top templates, and recent consent trends Given additional threshold breaches for the same entity within a suppression window of 30 minutes When detected Then duplicate alerts are suppressed and appended as updates to the open incident with updated metrics Given alert delivery channels configured (in-app, email, Slack) When an incident is created Then notifications are sent to all channels with retry up to 3 times on failure and final failure logged Given a user acknowledges an incident When acknowledged Then incident status changes to Acknowledged and subsequent notifications follow the suppression policy until Resolved Given the filtering rate falls below 80% of the threshold for two consecutive windows When evaluated Then the incident auto-resolves with reason Restored below threshold

Remediation Checklist Surfaced in Alerts and Dashboard

Given an incident categorized as Filtering suspected spam When the incident is opened Then a remediation checklist is displayed with actionable items: edit content (remove high-risk keywords, add brand intro), adjust pacing (reduce TPS), verify registration/10DLC, rotate sender if applicable, and trigger re-permission; each item has a one-click action or deep link Given a user executes an action from the checklist (e.g., reduce TPS, pause campaign, edit template) When completed Then the checklist updates with completion status, and an audit log is written with user, timestamp, action, and previous/new values Given role-based access control When an action requires elevated permission (e.g., pausing a campaign) Then only authorized roles can complete it; unauthorized attempts are blocked and logged Given remediation steps are applied When 24 hours elapse Then the system displays before/after KPIs for filtering rate, delivery rate, and confirmation rate on the incident timeline

Persist Carrier Insights on Consent Record and Inform Channel Selection

Given a patient consent record When new carrier feedback is received for that patient and channel Then the record is updated with last_blocked_at, last_category, provider, and a channel health score computed from the last 30 days of events Given an outbound message decision with multiple eligible channels When selecting a channel Then the selector avoids any channel with a Filtering suspected spam event within the last 72 hours unless an authorized user overrides with reason; if all channels are impaired, a re-permission attempt is queued instead Given consent expiration within 14 days and recent SMS filtering When launching a re-permission campaign Then the system recommends and defaults to the best alternate channel (email or voice) and language based on past recovery success for that patient cohort, and logs the rationale on the consent record Given channel health improves (filtering rate < 2% for 3 consecutive days with N >= 100 per day) When evaluated nightly Then the channel health score is upgraded and the channel becomes eligible again for selection

Consent Health Dashboard & Drilldowns

"As a practice owner, I want a clear view of our consent health and risks so that I can make informed decisions and keep outreach compliant."

Description

Deliver real-time dashboards that visualize opt-in rates, opt-out trends, consent decay pipeline, re-permission performance, and carrier filtering rates, sliceable by location, provider, channel, campaign, and time. Provide benchmarks, goal tracking, and anomaly detection with in-app and email/SMS alerts for threshold breaches. Enable drilldown to patient-level audit views showing the full consent timeline, message samples, and provenance. Support export (CSV) and API access for reporting, and embed key widgets on the SmileCue home page for quick status checks.

Acceptance Criteria

Real-Time Consent Health Dashboard Rendering

- Given the user opens the Consent Health Dashboard, When the page loads, Then KPI tiles for Opt-in Rate, Opt-out Trend, Consent Decay Pipeline, Re-permission Performance, and Carrier Filtering Rate are visible with labels and units. - Given a cold start, When the dashboard loads on a standard broadband connection, Then time-to-first-interaction is ≤2.5s at p95 and ≤4.0s at p99. - Given a new source event (opt-in, opt-out, carrier feedback, re-permission response), When it is ingested, Then the impacted metrics refresh within 60 seconds and show a “Last updated” timestamp to the minute. - Given today’s source-of-truth logs, When comparing sampled aggregates (n≥100 per metric), Then dashboard values deviate by ≤0.5% from source totals. - Given an upstream data outage, When the dashboard cannot fetch data, Then a non-blocking error banner displays with retry and status link, and cached metrics from ≤15 minutes ago are shown labeled as “stale.”

Slicing by Location, Provider, Channel, Campaign, and Time

- Given the dashboard is open, When the user expands the filter panel, Then multi-select controls for Location, Provider, Channel (SMS/Email/Voice), Campaign, and Time (Last 7/30/90 days, MTD, QTD, YTD, Custom Range) are available. - Given any combination of filters (≤50 selected values total), When Apply is clicked, Then all widgets refresh consistently to the same scope within 500ms after data return and the active filters appear as chips. - Given filtered state, When the user copies the URL or bookmarks the page, Then the full filter state is encoded in the URL and restored on revisit. - Given role-based access, When a user lacks access to a location or provider, Then those options are hidden and cannot be applied via URL. - Given a filter set that yields no results, When the dashboard refreshes, Then widgets display “No data in selected range” without errors and offer Clear Filters.

Benchmarks and Goal Tracking

- Given a metric tile, When the user toggles Benchmarks, Then the practice value, peer percentile band, and industry median display with tooltips citing the benchmark cohort and effective date. - Given edit permissions, When the user sets a goal target per metric (by global or per Location/Provider/Channel) and saves, Then the goal persists, is versioned with timestamp and editor, and renders progress (color-coded) on tiles and trends. - Given goals exist, When actuals cross warning (amber) or target (green) thresholds, Then tile colors update within 60 seconds of the underlying metric refresh. - Given read-only permissions, When viewing goals, Then inputs are disabled and an explanatory tooltip appears. - Given an audit review, When goals history is opened, Then prior values, editors, timestamps, and scope are listed chronologically.

Anomaly Detection and Threshold Alerts

- Given anomaly detection is enabled, When a metric deviates beyond configured rules (e.g., >2σ or >50% day-over-day for ≥3 hours), Then an anomaly badge appears on the metric and an incident is created. - Given alert channels are configured, When a threshold breach or anomaly is detected, Then an in-app notification, email, and optional SMS are sent with metric, scope, time window, baseline, and link to drilldown. - Given quiet hours are set, When a breach occurs during quiet hours, Then alerts are queued and summarized at quiet-hours end unless marked as critical. - Given repeated breaches of the same metric and scope, When multiple detections occur within 24 hours, Then alerts are deduplicated to one thread with updates appended. - Given a received alert, When the user clicks the link, Then they land on the pre-filtered dashboard/drilldown reflecting the alert context.

Drilldown to Patient-Level Consent Audit

- Given a metric widget, When the user clicks View Details, Then a drilldown table lists underlying patient events scoped to the selected filters with sortable columns and pagination. - Given a patient row is selected, When opening the audit view, Then the full consent timeline displays (timestamps, channel, campaign, consent text/version, event type, and status changes) with message samples and carrier feedback, including provenance (source system, user/API key, and IP/device for web submissions). - Given HIPAA access controls, When the user lacks permission for PHI, Then patient identifiers are masked in lists and details are inaccessible; access attempts are logged. - Given an audit view, When the user navigates back, Then breadcrumbs return them to the originating widget and filter context. - Given data retention policies, When viewing events older than retention limits, Then redacted placeholders appear with retained metadata (date, type) and a retention tooltip.

CSV Export and Reporting API

- Given the dashboard or drilldown is scoped, When the user clicks Export CSV, Then a UTF-8 CSV with headers reflecting the applied filters is generated server-side and downloaded or made available via a link for files >25MB. - Given large exports (>100k rows), When requested, Then export is chunked/streamed and a completion notification is sent; the file is available for ≥7 days with signed URL. - Given the Reporting API, When an authenticated client (OAuth2) requests the metrics endpoint with pagination and filters, Then the response includes totals, dimensions, and timestamps matching the data dictionary and dashboard values (±0.5%). - Given rate limits (e.g., 600 requests/min per tenant), When the limit is exceeded, Then 429 with retry-after is returned and logged. - Given an export or API access, When completed, Then an audit log entry is recorded with user/client, scope, timestamp, and record count.

Homepage Key Widgets Embedding

- Given the SmileCue home page loads, When widgets are enabled, Then key metrics (Opt-in Rate, Opt-out Trend sparkline, Consents expiring next 30 days, Carrier Filtering Rate, Open Alerts count) render above the fold. - Given a widget click, When the user selects a widget, Then they are deep-linked to the full dashboard with the corresponding filters applied. - Given configurable layout, When an admin reorders or toggles widgets, Then the layout persists per user and device (desktop/tablet/mobile) and reflows responsively. - Given data updates, When the home page is in focus, Then widgets refresh at least every 60 seconds and display a last-updated timestamp. - Given permission constraints, When a user lacks access to a metric’s scope, Then the widget is hidden or shows a masked state with a permission tooltip.

Compliance Guardrails & Audit Trail

"As a compliance officer, I want enforced guardrails and a provable audit trail so that we can demonstrate compliance and avoid penalties."

Description

Enforce HIPAA, TCPA, CTIA, and CAN-SPAM guardrails across Consent Pulse flows, including PHI redaction in re-permission outreach, required disclosures, opt-out keywords handling, quiet hours, and frequency caps. Maintain immutable, exportable audit logs of consent changes, message content hashes, delivery outcomes, and user/admin actions with timestamps and actor identity. Provide configurable retention policies, legal hold, and subject-access/deletion support. Block sends that violate rules and present actionable error messages with links to remediation. Generate audit-ready reports for regulators and carriers on demand.

Acceptance Criteria

Block Non-Compliant Sends in Real Time

Given a send is initiated for a recipient without active, channel-specific consent When the message is queued Then the system blocks the send, logs violated rule_id, and displays an error with remediation_url and API error code CP-401. Given message content lacks required channel disclosures When validation runs Then the send is blocked and the template editor highlights missing elements with a one-click Add Disclosure action. Given quiet hours or frequency caps would be violated When attempting to schedule Then the action is rejected and the UI suggests the next allowable send time in the recipient’s local timezone. Given carrier feedback flags a recipient as spam (e.g., 7726) within the last 30 days When any outreach is attempted Then the send is blocked and the recipient is marked Carrier-Blocked with reason_code and an appeal link. Given an opt-out keyword was received on the same channel within the last 24 hours When attempting to send Then the system blocks the send and references the opt-out timestamp in the error details.

PHI Redaction in Re-Permission Outreach

Given a re-permission campaign template contains PHI placeholders (e.g., appointment time, treatment) When a message is generated Then PHI tokens are replaced with generic placeholders and a PHI Redacted badge appears in preview. Given free-text content includes PHI per configured patterns or classifier confidence > 0.90 When saving the template Then the save is rejected with a list of flagged phrases and suggested safe rewrites. Given a user with override privilege attempts to bypass redaction When authorizing the send Then MFA is required and a policy_override event with justification is logged before the send can proceed. Given a voice re-permission script When generated Then the audio contains no PHI and uses only general language per policy.

Required Disclosures and Opt-Out Keyword Handling

Given SMS templates When previewed or sent Then "Reply STOP to opt out" and the practice name are appended; emails include physical address and unsubscribe link; voice calls include a spoken opt-out instruction. Given an inbound message matches STOP/END/CANCEL/UNSUBSCRIBE/QUIT (any case, with punctuation or emoji) When received Then channel consent is set to Opted-Out within 1 second, a confirmation is sent, and an audit entry is created. Given an inbound HELP keyword When received Then a CTIA-compliant help message with support contact is sent and logged. Given a previously opted-out recipient replies START/UNSTOP/YES to SMS or clicks a re-subscribe email link When processed Then consent changes to Opted-In with timestamp, source, and double opt-in if required by carrier.

Quiet Hours and Frequency Caps Enforcement

Given default quiet hours 8pm–8am recipient local time or practice-configured windows When scheduling or sending Then the system prevents delivery within the window unless marked Urgent under an approved policy with justification. Given per-recipient caps of max 3 SMS/week, 2 emails/week, 1 voice/week and max 1 message/day cross-channel When a send would exceed a cap Then the send is blocked and the UI shows remaining quota and next available slot. Given only a ZIP code is available to infer timezone When confidence < 0.70 Then stricter quiet hours (7pm–9am) are applied and the user is prompted to confirm or correct timezone. Given a DST transition occurs in the target timezone When scheduling sends That cross the transition Then delivery times are converted correctly and do not fall within quiet hours.

Immutable Audit Log of Consent and Messaging

Given any consent change, send attempt/outcome, content hash, templating variables, or user/admin action When it occurs Then an append-only audit entry with ISO-8601 UTC timestamp, actor_id, ip_address, rule_id, and SHA-256 content_hash is written within 2 seconds. Given an export request with filters (date range, patient, channel, action type, actor) When executed Then CSV and JSON exports for up to 1,000,000 records complete within 60 seconds; larger exports stream with progress. Given any attempt to alter or delete past audit entries When performed by any role Then the operation is denied and an integrity endpoint exposes a verifiable hash chain/Merkle root for immutability checks. Given carrier delivery receipts or spam feedback are received When processed Then they are linked to the original message audit entry with standardized reason codes and surfaced in the UI.

Retention Policies, Legal Hold, and DSAR Support

Given retention policies per data class (messages, audit logs, consent) When the policy job runs Then records older than the threshold are purged within 24 hours except those on legal hold, and a purge summary is logged. Given a legal hold is applied to a patient or matter When enabled Then all related records are exempt from purge until the hold is lifted, and hold status is visible in UI and audit logs. Given a Data Subject Access Request for a patient When initiated Then all relevant records are compiled and exported within 7 days with third-party identifiers redacted and an audit entry created. Given a deletion request compliant with policy When executed Then personal data is deleted except what is required for compliance, tokens are revoked, and a deletion receipt is logged.

Adds a sandbox to replay historical campaigns and synthetic cohorts to evaluate candidate bandit policies and guardrail settings before production. Supports counterfactual evaluation, A/A tests to verify false positive rates, and power calculators to estimate minimum samples and expected time-to-confidence. Produces policy comparison reports (e.g., regret, lift, exposure fairness) and generates safe default settings for new campaigns. Integrates with feature flags for staged rollouts and can backtest across SMS, email, and voice channels.

Acceptance Criteria

Cohort Carver

Auto-builds the right segments for clean insights: appointment type, provider, location, risk tier, language/age, guardian involvement, and more. Cohort Carver enforces fair splits, excludes tiny cohorts from biasing results, and tags each result with context. You see exactly what works for whom—then roll out with precision.

Requirements

Add admin settings to control QR expiration, allowed payment methods and wallets, tipping, partial payments, localization, and branding. Implement clinic tablet kiosk mode with guided flow, app/pinned-browser locking guidance, inactivity timeout, automatic session cleanup, and optional device registration. Configure default receipt delivery (SMS/email) and staff permissions for QR features. Provide a lightweight dashboard for monitoring active sessions and recent payments.

Product Details

Vision & Mission

Problem & Solution

Details & Audience

User Personas

Treatment Closer Carla

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Pediatric Parent Priya

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Ortho Optimizer Owen

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Surgery Prep Sam

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Compliance Custodian Casey

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Access Advocate Carmen

Background

Needs & Pain Points

Needs

Pain Points

Psychographics

Channels

Product Features

Jurisdiction Rules

Requirements

Jurisdiction Resolution Engine

Description

Acceptance Criteria

Rule Library & Versioning

Description

Acceptance Criteria

Consent Matrix & Double Opt-In

Description

Acceptance Criteria

Quiet Hours Enforcement & Rescheduling

Description

Acceptance Criteria

Compliance Pre-Check Guardrails

Description

Acceptance Criteria

Immutable Compliance Audit Trail

Description

Acceptance Criteria

Evidence Vault

Requirements

Tamper-Evident Consent Ledger

Description

Acceptance Criteria

One-Click Evidence Pack Export

Description

Acceptance Criteria

Role-Based Access & Least-Privilege Controls

Description

Acceptance Criteria