For the technical audience

Decisions

Every architecture decision record (ADR) behind TelltaleDNS: what we knew, what we chose, and what it costs. This page is built from the specification on every change, so it's always the current record.

151 decisions. Accepted 95 · Agreed with the project owner. Proposed 55 · Chosen during implementation where the specification left a gap. It is in effect, and waits for the owner's review. Superseded 1 ·

ADR-001 Language: RustAcceptedPerformance and footprint are paramount: a small, steady memory footprint on a Raspberry Pi and microsecond cache hits.
ADR-016 List fetcher behavior and configurationAcceptedFLTUPSFLT-004 and spec/05 §3.4 step 1 define the fetcher's duties (conditional GETs, size caps, retries, stored sources) but not its configuration, scheduling, name resolution, or edge cases.
ADR-019 Deterministic device anomaly detectionAcceptedOBSThe owner wants TelltaleDNS to notice when a device behaves differently: abnormal traffic, many queries to one domain, or IoT/appliance phone-homes, in a safe and deterministic way.
ADR-021 Groups, clients, and identificationAcceptedFLTFLT-005/006 and spec/03 §3 step 2 define groups and the identification chain, but not the configuration, the trust model for client-supplied identity, or how group lists meet the compiled snapshot.
ADR-027 Query-log segment format and searchAcceptedspec/06 §4 defines the query log: hourly columnar segments, blocks of up to 8192 rows, per-column encodings with zstd, a block index with a 1 KiB bloom over name and client IDs, a segment dictionary, dictionary-first search, and a small search pool with "1 thread on Pi by default".
ADR-029 Local sign-in detailsAcceptedAGTAPIspec/08 §6 and API-003 define local users (Argon2id), session cookies with CSRF, opt-in HTTP Basic, scoped API tokens, TOTP, lockout, RBAC, and a first-run setup token.
ADR-032 Live tail over Server-Sent EventsAcceptedOBSOBS-008 / 06 §6: GET /api/v1/queries/stream (SSE) "or /ws", server-side filters (client, group, status set, qname glob, upstream, min latency, node), and a per-subscriber rate cap (default 500 events/s) with inline drop counts.
ADR-034 OIDC sign-in: library, flow, and account rulesAcceptedAPIAPI-004 / 08 §6: Authorization Code + PKCE, discovery, multiple providers, claim → role mapping, JIT provisioning, optional verified email, back-channel and RP-initiated logout, ID-token validation with JWKS rotation, local sessions after sign-in, a canonical public_url, and disable_local_login with a break-glass admin from allowed_admin_networks.
ADR-035 Helm chart: allInOne first, client-IP proof in CIAcceptedOPST4.1 / OPS-002/003 asks for allInOne, scaled, and daemonSet shapes, Services with externalTrafficPolicy: Local, PDB, HPA, probes, NetworkPolicy, ServiceMonitor, cert-manager, existingSecret everywhere; AC: ct install on kind and k3d arm64, DNS via the LB, and client IPs preserved in the query log in an e2e test.
ADR-044 Cluster channel v1: identity files, reusable join tokens, and peer trustAcceptedCLUT5.1 implements CLU-001 under spec/12 §3, which fixes the shape (Ed25519 CA, join token with CA fingerprint + URLs + secret, 90-day node certificates, mTLS over HTTP/2 with protobuf, persistent streams, replicas dial out) but not the token format, how peers name each other in TLS, where identity lives, or whether a token is single-use.
ADR-121 Long pages get tabs; a tab never hides troubleProposedthe Cluster page had grown to about ten panels, Settings → System to eight (node housekeeping mixed with how queries are handled), and Clients to three tables, one of them a router's whole client list (57 rows on the owner's network).