Architecture decisions

The ADRs in docs/decisions. Short, accepted, dated.

Source files live in `docs/decisions/`.

0001 — Clean-room and licence

Write every line ourselves. Reuse only non-copyrightable principles (daily-salted hash, no cookies, session windows). AGPL on the server; MIT on client packages so they can be pasted into any site. Cloud resellers must publish modifications.

0002 — Postgres, not ClickHouse

The cloud database is Supabase Postgres 17. Self-hosters expect one compose file. Partition events by month, serve the dashboard from rollups, leave a storage interface for ClickHouse later. Fast until tens of millions of events.

0003 — Daily-salted visitor hash

SHA-256(daily_salt || site_id || ip || user_agent). Salt rotates 00:00 UTC. IP discarded. A returning visitor tomorrow is a new hash. The limit is displayed in "What we cannot know."

0004 — Layered actor classification

Five actors. Curated UA list, vendor IP / rDNS when published, headless heuristics. Assistant referrers mark human_via_ai. Dashboards default to humans. Agent metrics are task-oriented, not bounce rate.

0005 — Aggregates-only LLM

Insights receive rollup rows only. Providers are pluggable, including local Ollama. Every derived number is observed or inferred. The privacy guarantee holds when AI is enabled.