Architecture Decisions
Architecture Decision Records (ADRs) for cotel. Each record documents a significant technical choice: the context that made it necessary, the options considered, the decision made, and its consequences.
New ADRs go in this directory as NNNN-short-title.md, numbered sequentially.
Records
| # | Title | Status |
|---|---|---|
| ADR-0001 | Storage Engine — DuckDB | Accepted |
| ADR-0002 | Dashboard — React SPA + JSON API | Accepted |
| ADR-0003 | Release Policy and Versioning | Accepted |
| ADR-0004 | Multi-User Telemetry Separation via user.id | Accepted |
| ADR-0005 | Export/Import Format — Versioned ZIP/CSV/Manifest | Accepted |
| ADR-0006 | Cloudflare Tunnel + In-App Bearer Tokens for OTLP Auth | Accepted |
| ADR-0007 | GitHub Issue Intake Security Hardening | Accepted |
| ADR-0008 | Per-agent telemetry identity must not live in shared settings.json env | Accepted |
| ADR-0009 | daily_usage roll-up normalises empty/NULL keys to an unknown sentinel | Accepted |
| ADR-0010 | Guard schema migrations behind a recorded version | Accepted |
| ADR-0011 | Users list — time-ranged stats, server-side sort and pagination | Accepted |
| ADR-0012 | Tools list — time-ranged stats, server-side sort and pagination | Accepted |
| ADR-0013 | spans carries no derived columns: drop duration_ms | Accepted |
| ADR-0014 | Overview — one range selector every panel obeys | Accepted |
| ADR-0015 | Overview — spans and cost share one block, and one plot | Accepted |
| ADR-0016 | Overview — an activity grid, one cell per bucket | Accepted |
| ADR-0017 | The chart-palette ruler is pinned, and a Go test holds it | Accepted |
| ADR-0018 | DuckDB driver — duckdb/duckdb-go/v2, with the storage format pinned | Accepted |
| ADR-0019 | CI never mutates an issue: recovery wakes the alert's assignee | Superseded by ADR-0021 |
| ADR-0020 | Recovery arrives as a new issue, and dedup is time-bounded | Superseded by ADR-0021 |
| ADR-0021 | Recovery wakes the alert's assignee, and dedup is time-bounded | Accepted |
| ADR-0022 | The health probe's scheduler lives outside this repo | Superseded by ADR-0025 |
| ADR-0023 | Snapshots: EXPORT DATABASE to Parquet, on a timer, from inside cotel | Accepted |
| ADR-0024 | The off-host copy is a Pi-side pull, and it cannot be an rsync of the volume | Rescinded by the owner 2026-10-19 |
| ADR-0025 | cotel is watched by a best-effort ingest probe in GitHub Actions | Accepted |
| ADR-0026 | The deploy host asks /healthz on a schedule, and it pages | Accepted |
| ADR-0027 | Users become actors, down to the schema | Accepted |
| ADR-0028 | Ingest keys authorize, actor tokens identify | Accepted |
| ADR-0029 | Paperclip agents are identified by paperclip.agent.id | Accepted |
| ADR-0030 | Codex spans without a session are dropped at ingest | Accepted |