Design Decisions (ADRs)
Architecture Decision Records live in adrs/ and record why each significant decision was made (constitution §5.3). All twelve are Accepted. Summaries below; follow the link for full context and alternatives.
| ADR | Decision | Constitution refs |
|---|---|---|
| 001 | API versioning via URL prefix /v1 | §7.3, §15 |
| 002 | Error envelope = RFC 9457 problem+json | §7.3, §7.5 |
| 003 | Contract tooling = @hono/zod-openapi (contract-first) | §7.3, §7.9 |
| 004 | CLI auth = OAuth PKCE | §7.12, §7.15 |
| 005 | CLI = TypeScript, distributed via npm | §7.15, §8.1 |
| 006 | Real-time transport = polling for MVP; DO WebSocket the planned upgrade | §7.14.6, §8.4 |
| 007 | Supply-chain tooling = OSS stack (SBOM, osv-scanner, gitleaks) | §9.6, §11.9 |
| 008 | i18n = Paraglide/Inlang + native Intl | §7.16, §8.1 |
| 009 | PWA tooling = post-build workbox-build + prerendered app shell | §7.14.2, §8.1 |
| 010 | Auth UI = Clerk prebuilt components | §7.16.1, §7.12 |
| 011 | Event push = signal-only WebSocket over a per-user inbox Durable Object | §7.14.6, §8.1, §8.4 |
| 012 | Docs toolchain = Astro Starlight (build-time tooling; no §8.1 amendment) | §8.1, §8.2, §9.6, §14 |
Notable threads
Section titled “Notable threads”- Real-time transport (006 → 011). Polling was the correct MVP transport; ADR-011 realises ADR-006’s named upgrade as signal-only WebSocket push over the
SyncInboxDurable Object, demoting polling to a fallback. ADR-006 remains Accepted, not superseded. - Contract-first (003). The OpenAPI document is generated from Zod schemas and is the single source of truth shared by all clients — including the API Reference on this site.
- Stack governance (012). Durable Objects (011) extended the production stack and required a §8.1 constitution amendment; the documentation site (012) is build-time tooling reusing the approved Astro stack, so it did not.