fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs(html): data-flow-explainer §06 tracing + di-explainer §08 instrumentation symbols

Browse Source 
Inserts a new §06 "Tracing & error capture" between the existing
"Tradeoffs by part" (§05) and the verdict (which moves to §07).
Includes the trace tree (HTTP → tRPC → controller → use-case → repo
→ Payload), capture-rules table (where captureException fires per
layer + the no-capture rule for defineErrorMiddleware), the
__sentryReported double-report guard explanation, and the R31–R38
PII rule list. Adds matching CSS (.trace-tree / .capture-rules /
.pii-rules) tuned to the existing dark-paper palette and Fraunces
heading font. Updates the contents nav from 6 → 7 columns.

di-explainer.html gets a new §08 "Instrumentation symbols" with cards
for TRACER and LOGGER, the bindAll() Rule-0 wiring path, and a note
on why feature containers also bind the symbols. Two-column grid
collapses to one on narrow viewports.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Danijel Martinek
2026-05-07 20:37:46 +02:00
parent 85513ccbf9
commit 0a248d5be0
2 changed files with 180 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs/architecture/di-explainer.html
View File

@@ -641,11 +641,43 @@ footer .colophon {
font-size: 10.5px; color: var(--ink-3); letter-spacing: 0.04em;
}
/* ─── §08 Instrumentation symbols (Plan 10) ──────────────────────── */
.instrumentation-grid {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 36px;
margin-top: 24px;
}
.trace-h3 {
font-family: "Fraunces", serif;
font-weight: 500;
font-size: 1.05rem;
margin: 24px 0 12px;
color: var(--paper);
}
.trace-h3:first-child { margin-top: 0; }
.trace-p {
margin: 0 0 16px;
max-width: 60ch;
font-size: 0.95rem;
}
.trace-tree {
background: var(--ink-2, rgba(0,0,0,.32));
padding: 1rem 1.25rem;
border-radius: 4px;
overflow-x: auto;
font-family: "JetBrains Mono", monospace;
font-size: 0.82rem;
line-height: 1.55;
margin: 0 0 18px;
}
/* ─── Responsive ─────────────────────────────────────────────────── */
@media (max-width: 1100px) {
.frame { padding: 0 32px; }
.cast-grid, .bindings-grid, .modes-state-grid, .bypass-grid { grid-template-columns: 1fr; }
.cast-grid, .bindings-grid, .modes-state-grid, .bypass-grid, .instrumentation-grid { grid-template-columns: 1fr; }
ol.contents { grid-template-columns: repeat(2, 1fr); }
.title-block { grid-template-columns: 1fr; gap: 32px; }
.conditions-head, .conditions-row { grid-template-columns: 1fr; gap: 4px; }
@@ -673,6 +705,7 @@ footer .colophon {
<li><a href="#modes"><span class="num">05</span>Three modes</a></li>
<li><a href="#conditions"><span class="num">06</span>Conditions</a></li>
<li><a href="#tests"><span class="num">07</span>Tests bypass</a></li>
<li><a href="#instrumentation"><span class="num">08</span>Instrumentation symbols</a></li>
</ol>
</div>
</header>
@@ -1126,6 +1159,39 @@ footer .colophon {
</div>
</section>
<!-- ─── 08 ─ INSTRUMENTATION SYMBOLS (Plan 10) ────────────────────────── -->
<section id="instrumentation">
<div class="section-head">
<div class="section-num">§ 08</div>
<div>
<h2 class="section-title">Instrumentation <em>symbols</em>.</h2>
<p class="section-blurb">Plan 10 added two new symbols to the per-feature container — <code>TRACER</code> and <code>LOGGER</code> — bound by a separate Rule 0 in <code>bindAll()</code> that's <strong>orthogonal</strong> to the repo binding mode. The DSN env var decides Sentry vs Noop; <code>USE_DEV_SEED</code> / <code>NODE_ENV</code> decide real vs mock repos.</p>
</div>
</div>
<div class="instrumentation-grid">
<div>
<h3 class="trace-h3"><code>INSTRUMENTATION_SYMBOLS.TRACER</code></h3>
<p class="trace-p">Bound by either <code>bindNoopInstrumentation</code> or <code>bindSentryInstrumentation</code> to <code>NoopTracer</code> or <code>SentryTracer</code>. Decided by Rule 0: DSN env present → Sentry; otherwise Noop.</p>
<h3 class="trace-h3"><code>INSTRUMENTATION_SYMBOLS.LOGGER</code></h3>
<p class="trace-p">Same rule, same lifecycle. <code>NoopLogger</code> in the absence of a DSN; <code>SentryLogger</code> when DSN is set. The Sentry adapter applies the <code>__sentryReported</code> double-report guard internally — call sites don't manage the flag.</p>
</div>
<div>
<h3 class="trace-h3">Wiring path</h3>
<pre class="trace-tree"><code>bindAll()
└─ resolveInstrumentation() ← Rule 0 (DSN check)
└─ Noop or Sentry binders ← bind to sharedContainer
└─ bindProductionX(config, tracer, logger)
└─ feature container also binds TRACER + LOGGER
└─ withSpan(tracer, ...) at every use case + controller</code></pre>
<p class="trace-p"><strong>Why per-feature containers also get the binding:</strong> repository classes resolve TRACER/LOGGER through the container; controllers and use cases receive instrumentation via the bind-time wrapper instead.</p>
</div>
</div>
</section>
</main>
<footer class="frame">