content/engineering/modules/analytics.html

<article class="doc" id="doc-modules-analytics" aria-hidden="true"><div class="strip"><span class="path">modules/analytics.md</span><span class="tag">Engineering, modules</span><span class="meta">~1 min read</span></div>
<h1>Module: <code>analytics</code></h1>
<blockquote>
<p>Part of the Travi AI Agent monolith (<code>app/modules/analytics/</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="">Honest numbers: fixed denominators, execution reports by task category, outcome ingestion with coverage flags.</td>
</tr>
<tr>
<td data-label=""><strong>Owns (data)</strong></td>
<td data-label="">outcome_event, report projections (read models)</td>
</tr>
<tr>
<td data-label=""><strong>Public surface</strong></td>
<td data-label=""><code>/admin/reports/execution</code>, <code>/admin/reports/outcomes</code></td>
</tr>
<tr>
<td data-label=""><strong>Depends on</strong></td>
<td data-label="">episode/notification event stream (outbox), ingestion (ADT/HIE/claims)</td>
</tr>
<tr>
<td data-label=""><strong>Requirements owned</strong></td>
<td data-label="">ADM-004/007</td>
</tr>
<tr>
<td data-label=""><strong>Constraining ADRs</strong></td>
<td data-label="">ADR-016</td>
</tr>
<tr>
<td data-label=""><strong>Key references</strong></td>
<td data-label="">adr/ADR-016.md</td>
</tr>
</tbody>
</table></div>
<hr/>
<h2 id="doc-modules-analytics--h1">Rules that must never break</h2>
<ol>
<li><strong>Denominators are frozen (ADR-016):</strong> offered / activated / engaged / completed. <em>Offered</em> is the only valid outcome-rate denominator; every report footer prints all four plus coverage %.</li>
<li><strong>Coverage honesty.</strong> ADT/HIE outcome coverage &lt;80% flags readmission metrics; &lt;50% suppresses them. <code>completeness_note</code> rides every outcome_event.</li>
<li><strong>Execution categories</strong> map 1:1 from task states: required, attempted, completed, blocked, escalated, unresolved, no invented buckets.</li>
<li><strong>Small-cell suppression:</strong> aggregates with n&lt;11 are suppressed in any export.</li>
</ol>
<div class="pn"><a class="pn-prev" href="#"></a><a class="pn-next" href="#"></a></div></article>