content/engineering/modules/notification.html

<article class="doc" id="doc-modules-notification" aria-hidden="true"><div class="strip"><span class="path">modules/notification.md</span><span class="tag">Engineering, modules</span><span class="meta">~1 min read</span></div>
<h1>Module: <code>notification</code></h1>
<blockquote>
<p>Part of the Travi AI Agent monolith (<code>app/modules/notification/</code>). Read <code>00-overview.md</code> §3 (hard rules) before changing anything here.</p>
</blockquote>
<div class="tbl-wrap"><table class="plain col-table compact"><colgroup><col class="col-auto"/><col class="col-lg"/></colgroup>
<thead>
<tr>
<th></th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td data-label=""><strong>Purpose</strong></td>
<td data-label="">Channel ladders, quiet hours, suppression, templates, and the silent-deterioration detector.</td>
</tr>
<tr>
<td data-label=""><strong>Owns (data)</strong></td>
<td data-label="">notification_message, templates (+versions/approvals)</td>
</tr>
<tr>
<td data-label=""><strong>Public surface</strong></td>
<td data-label="">internal send API; <code>/webhooks/twilio</code>, <code>/webhooks/ses</code></td>
</tr>
<tr>
<td data-label=""><strong>Depends on</strong></td>
<td data-label="">identity (consents/channels), episode (outbox events), agents (engagement)</td>
</tr>
<tr>
<td data-label=""><strong>Requirements owned</strong></td>
<td data-label="">ENG-002/004/012, EDU-002/007, PAT-003 suppression</td>
</tr>
<tr>
<td data-label=""><strong>Constraining ADRs</strong></td>
<td data-label="">ADR-013, ADR-015</td>
</tr>
<tr>
<td data-label=""><strong>Key references</strong></td>
<td data-label="">reference/operations.md §16.5 (jobs)</td>
</tr>
</tbody>
</table></div>
<hr/>
<h1>13. Notification Orchestration</h1>
<h2 id="doc-modules-notification--h1">13.1 Decision Inputs &amp; Ladders</h2>
<p>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:</p>
<div class="tbl-wrap"><table class="col-table compact"><colgroup><col class="col-xs"/><col class="col-lg"/><col class="col-md"/></colgroup>
<thead>
<tr>
<th>Tier</th>
<th>Ladder &amp; Timing</th>
<th>Caps</th>
</tr>
</thead>
<tbody>
<tr>
<td data-label="Tier">Routine</td>
<td data-label="Ladder &amp; Timing">Push/in-app → +24 h one reminder → adaptive retry next engagement window</td>
<td data-label="Caps">≤2 touches/task; ≤3 total/day</td>
</tr>
<tr>
<td data-label="Tier">Important</td>
<td data-label="Ladder &amp; Timing">Push → +6 h SMS → +24 h SMS → +48 h automated voice → caregiver (consented)</td>
<td data-label="Caps">≤5 touches/task; voice only 09:00–19:00</td>
</tr>
<tr>
<td data-label="Tier">Safety (L3)</td>
<td data-label="Ladder &amp; Timing">Immediate approved instructions on all consented channels + clinical endpoint alert</td>
<td data-label="Caps">No caps; quiet hours overridden; page ops on delivery failure</td>
</tr>
</tbody>
</table></div>
<h2 id="doc-modules-notification--h2">13.2 Hard Rules</h2>
<ul>
<li>Suppression ≤60 s of completion/cancel/supersede/opt-out via outbox drain (PAT-003, ENG-004), measured and alarmed.</li>
<li><strong>No PHI in any payload</strong> (push/SMS/email subject+body): generic prompt + deep link only; templates linted in CI for PHI slots.</li>
<li>Templates: versioned, owner + approval date required (EDU-007); languages EN/ES at launch; voice = SSML from same templates.</li>
<li>Micro–teach-back only when the answer changes an action/measurement (EDU-002); never default daily surveys.</li>
<li>Monitoring-language lint: outbound copy must not imply clinician review or response times (CLN-008).</li>
</ul>
<h2 id="doc-modules-notification--h3">13.3 Silent-Deterioration Detector (ENG-012 / ADR-013)</h2>
<p>Beat job q15 min: episodes <code>active</code> with a critical-tier task lacking any patient/caregiver interaction for ≥<code>safety.silent_hours_caregiver</code> (48) after ≥1 prior successful engagement → caregiver alert + flag; ≥<code>safety.silent_hours_ops</code> (72) → ops route per ADR-011 and mark <code>silent_deterioration</code> on the episode (feeds pilot safety endpoints). Detector is idempotent and audit-logged; thresholds cohort-configurable without release.</p>
<div class="pn"><a class="pn-prev" href="#"></a><a class="pn-next" href="#"></a></div></article>