Skip to content

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 ​

#TitleStatus
ADR-0001Storage Engine — DuckDBAccepted
ADR-0002Dashboard — React SPA + JSON APIAccepted
ADR-0003Release Policy and VersioningAccepted
ADR-0004Multi-User Telemetry Separation via user.idAccepted
ADR-0005Export/Import Format — Versioned ZIP/CSV/ManifestAccepted
ADR-0006Cloudflare Tunnel + In-App Bearer Tokens for OTLP AuthAccepted
ADR-0007GitHub Issue Intake Security HardeningAccepted
ADR-0008Per-agent telemetry identity must not live in shared settings.json envAccepted
ADR-0009daily_usage roll-up normalises empty/NULL keys to an unknown sentinelAccepted
ADR-0010Guard schema migrations behind a recorded versionAccepted
ADR-0011Users list — time-ranged stats, server-side sort and paginationAccepted
ADR-0012Tools list — time-ranged stats, server-side sort and paginationAccepted
ADR-0013spans carries no derived columns: drop duration_msAccepted
ADR-0014Overview — one range selector every panel obeysAccepted
ADR-0015Overview — spans and cost share one block, and one plotAccepted
ADR-0016Overview — an activity grid, one cell per bucketAccepted
ADR-0017The chart-palette ruler is pinned, and a Go test holds itAccepted
ADR-0018DuckDB driver — duckdb/duckdb-go/v2, with the storage format pinnedAccepted
ADR-0019CI never mutates an issue: recovery wakes the alert's assigneeSuperseded by ADR-0021
ADR-0020Recovery arrives as a new issue, and dedup is time-boundedSuperseded by ADR-0021
ADR-0021Recovery wakes the alert's assignee, and dedup is time-boundedAccepted
ADR-0022The health probe's scheduler lives outside this repoSuperseded by ADR-0025
ADR-0023Snapshots: EXPORT DATABASE to Parquet, on a timer, from inside cotelAccepted
ADR-0024The off-host copy is a Pi-side pull, and it cannot be an rsync of the volumeRescinded by the owner 2026-10-19
ADR-0025cotel is watched by a best-effort ingest probe in GitHub ActionsAccepted
ADR-0026The deploy host asks /healthz on a schedule, and it pagesAccepted
ADR-0027Users become actors, down to the schemaAccepted
ADR-0028Ingest keys authorize, actor tokens identifyAccepted
ADR-0029Paperclip agents are identified by paperclip.agent.idAccepted
ADR-0030Codex spans without a session are dropped at ingestAccepted

Released under the MIT License.