Architecture: how Tracabit processes events

Every event follows the same short path: a browser beacon hits POST /analytics, the Telemetry engine authenticates the request against the project's API key, normalizes the payload, and writes it to the ACID store. The whole hop is designed to stay under ten milliseconds so the tracker never slows your page.

At launch, Tracabit uses Tero — an embedded ACID JSON store — for durability and simple operations. Each event updates a daily metric document keyed by project and date, plus a capped recent-events log. Because writes are per-document rather than a full-file rewrite, cost per event stays flat as your data grows.

When you need to scale past a single node, the production path migrates to ClickHouse. Materialized views keyed by (project, date) aggregate pageviews, sessions, and dimensions in near real time, and the GET /metrics API reads those views with p95 latency under 50ms for a 30-day range at 10M+ events.

The read side is intentionally simple: one documented endpoint, one stable JSON shape. Whether a human dashboard or an AI agent calls GET /metrics, the contract is identical — which is why the same API powers both.