How it works

ARCHITECTURE

Every payload travels the same path: detect the shape, parse it with a versioned parser, normalize to one canonical event, dedupe on identity, and check for drift before it's stored. These diagrams trace that path and the two things that make it trustworthy — the replay harness and silent-null detection.

Diagram 1

High-level architecture

AI Providers
OpenAI · Anthropic · Cursor send usage payloads
Version Detection
fingerprint the raw shape, pick the right parser version
Versioned Parser
pure parse(raw) → CanonicalEvent
Canonical Event
one shape every reader reads
Deduplication
upsert on a deterministic identity-only key
Drift Detection
structural + silent-null, runs on every ingest
Database
events · raw_payloads (+golden) · drift_alerts
API
Fastify reads — events, alerts, replay, vitals, inspect
Dashboard
the read-only Signal Room
Diagram 2

Ingestion pipeline

live flow

A single payload flowing end to end.

Payload Received
Identify Provider
Choose Parser Version
Normalize
Generate Dedup Key
Check Drift
Store Event
Update Dashboard
Diagram 3

Replay harness

Re-run every parser version over history and diff against the golden output — so a parser change can never silently break old data.

Historical Payloads
the full stored corpus + each golden
Parser v1
the version captured at ingest
Golden Output
what we recorded then
Parser v2
the candidate / fixed version
New Output
re-parse today
Compare
semantic diff, golden vs new
Regression?
did any payload change for the worse / throw
✓ Pass
identical, or improved
✗ Fail
a parser change broke history
green — passed (matches golden) yellow — drift fixed (v2 reparsed) red — regression / threw
Diagram 4

Why silent-null is dangerous

The failure that doesn't throw. A field reports reliably, the provider moves it, and the parser keeps "succeeding" while the value reads null.

Field population over time
100%100%100%100%
Provider Schema Changes
cost moves cost → pricing.cost — no error thrown
4%
⚠ Critical Alert
populated >90% historically, ~0% now — cost reads null in silence
Diagram 5

Canonical event transformation

Three different provider schemas, one unified structure.

OpenAI payload
{
  "model": "gpt-4o",
  "usage": { "prompt_tokens": 412 },
  "cost": { "amount_usd": 0.014 }
}
Claude payload
{
  "model": "claude-3-5-sonnet",
  "usage": { "input_tokens": 412 },
  "cost_usd": 0.014
}
Cursor payload
{
  "model": "cursor-fast",
  "tokens": { "in": 412 },
  "billing": { "usd": 0.014 }
}
Versioned Parsers
one per provider/version — each maps its quirks
CanonicalEvent — one unified structure
{
  "provider": "…",
  "model": "…",
  "usage": { "input_tokens": 412 },
  "cost": { "amount_usd": 0.014 }
}