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

docs: introduce product analytics as a fourth capture channel (ADR-024)

Browse Source 
ADR-024 codifies IAnalytics as an optional-core channel parallel to
IAuditLog. Mirrors the audit pattern (inline emission, manifest field,
brand at bind time, ESLint cross-check) with three deliberate
divergences: no `mutates` gate on the brand check, flush() on the
interface for batched server-side SDKs, and a React provider scaffold
in core-analytics/react so server + client share the same contract.

PII boundary is explicitly distinct from ADR-017's observability policy:
traits-allowed at the interface, consumer owns consent + retention.

Glossary updated with IAnalytics and withAnalytics entries.
This commit is contained in:
Danijel Martinek
2026-05-18 12:29:44 +02:00
parent 8cb531e0cd
commit d66aba32e3
2 changed files with 229 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/glossary.md
View File

@@ -251,8 +251,12 @@ The capture interface. Same three-impl shape as `ITracer`. Used for exception re
**Metrics** (`IMetrics`):
The counter/gauge/histogram interface. Same three-impl shape.
**`withSpan`** / **`withCapture`** / **`withAudit`**:
The three wrapper composers applied at DI bind time. Composition: `withSpan(tracer, opts, withCapture(logger, tags, withAudit(auditLog, schema, factory(deps))))` — `withSpan` outermost. Together they attach the `Instrumented` / `Captured` / `Audited` brands.
**Analytics** (`IAnalytics`):
The product-analytics interface, lives in `@repo/core-analytics` (optional core, scaffolded via `pnpm turbo gen core-package analytics`). Three methods: `track(event, properties?, user?)`, `identify(user)`, `pageView(path, properties?)`. Same three-impl shape as `ITracer`/`ILogger`/`IMetrics`. Used for funnel/cohort/retention analysis; structurally distinct from `IAuditLog` (which is compliance-driven) and from `IEventBus` (which is cross-feature action routing). Server-only by manifest gate; consumer wires React provider for client-side via `@repo/core-analytics/react`.
_Avoid:_ confusing analytics events with cross-feature events (bus) or audit events (compliance) — they're three orthogonal capture channels.
**`withSpan`** / **`withCapture`** / **`withAudit`** / **`withAnalytics`**:
The four wrapper composers applied at DI bind time. Composition is nested with `withSpan` outermost; each layer attaches a brand: `withSpan` → `Instrumented`, `withCapture` → `Captured`, `withAudit` → `Audited` (when manifest declares `audits`), `withAnalytics` → `Analyzed` (when manifest declares `analyticsEvents`).
**Span**:
A traced unit of work. Emitted by `tracer.startSpan(...)` (inline in repos) or `withSpan(...)` (composed for use cases + controllers).