modules/notification.mdEngineering, modules~1 min read

Module: notification

Part of the Travi AI Agent monolith (app/modules/notification/). Read 00-overview.md §3 (hard rules) before changing anything here.
Purpose Channel ladders, quiet hours, suppression, templates, and the silent-deterioration detector.
Owns (data) notification_message, templates (+versions/approvals)
Public surface internal send API; /webhooks/twilio, /webhooks/ses
Depends on identity (consents/channels), episode (outbox events), agents (engagement)
Requirements owned ENG-002/004/012, EDU-002/007, PAT-003 suppression
Constraining ADRs ADR-013, ADR-015
Key references reference/operations.md §16.5 (jobs)

13. Notification Orchestration

13.1 Decision Inputs & Ladders

The orchestrator resolves: task tier, patient tz + quiet hours (default 21:00–08:00 local), language, accessibility prefs, channel consents, response history (least-burdensome-first, ENG-002), and suppression state. Ladders:

Tier Ladder & Timing Caps
Routine Push/in-app → +24 h one reminder → adaptive retry next engagement window ≤2 touches/task; ≤3 total/day
Important Push → +6 h SMS → +24 h SMS → +48 h automated voice → caregiver (consented) ≤5 touches/task; voice only 09:00–19:00
Safety (L3) Immediate approved instructions on all consented channels + clinical endpoint alert No caps; quiet hours overridden; page ops on delivery failure

13.2 Hard Rules

  • Suppression ≤60 s of completion/cancel/supersede/opt-out via outbox drain (PAT-003, ENG-004), measured and alarmed.
  • No PHI in any payload (push/SMS/email subject+body): generic prompt + deep link only; templates linted in CI for PHI slots.
  • Templates: versioned, owner + approval date required (EDU-007); languages EN/ES at launch; voice = SSML from same templates.
  • Micro–teach-back only when the answer changes an action/measurement (EDU-002); never default daily surveys.
  • Monitoring-language lint: outbound copy must not imply clinician review or response times (CLN-008).

13.3 Silent-Deterioration Detector (ENG-012 / ADR-013)

Beat job q15 min: episodes active with a critical-tier task lacking any patient/caregiver interaction for ≥safety.silent_hours_caregiver (48) after ≥1 prior successful engagement → caregiver alert + flag; ≥safety.silent_hours_ops (72) → ops route per ADR-011 and mark silent_deterioration on the episode (feeds pilot safety endpoints). Detector is idempotent and audit-logged; thresholds cohort-configurable without release.