ADR-0001 — Cloudflare stack
Choose Cloudflare (Workers + D1 + R2 + Pages + Cron) as the runtime for everything Helm.
ADR-0002 — D1 over Postgres
Use Cloudflare D1 (SQLite) as the per-shop database, not Postgres or any other RDBMS.
ADR-0003 — Single-tenant architecture
One Worker, one D1, one R2 bucket per shop. No shared databases. No tenant_id columns.
ADR-0004 — Vanilla JS, no framework
The Worker is plain JavaScript. The operator UI is plain HTML and small JS modules. No React, no Hono, no Remix.
ADR-0005 — Tamper-chain audit log
Every mutation writes a hash-chained audit row. Tampering with history breaks the chain forward.
ADR-0006 — Data ownership commitment
The shop owns its data. Helm provides on-demand full export at no cost. No data hostage situations.
ADR-0007 — GitHub Actions for CI
Use GitHub Actions for CI/CD. Per-shop deploys triggered by per-shop branches.
ADR-0008 — Slice-by-slice build
Ship vertical slices that cross every layer rather than horizontal layers that span every feature.
ADR-0009 — Anthropic Claude over OpenAI
Use Claude as the LLM for the AI Support bubble. Anthropic's prompt caching, safety alignment, and long-context handling fit our use case best.
ADR-0010 — AI opt-out per customer
Each customer can opt out of having their identifying data included in AI queries.
ADR-0011 — Stripe Terminal as the card processor
Use Stripe Terminal (BBPOS WisePOS E) for in-shop card processing. Each shop owns its Stripe account.
ADR-0012 — Twilio for SMS
Use Twilio for outbound SMS. One Kvick-owned account with per-shop sub-accounts.
ADR-0013 — PBKDF2 for PIN hashing
Use PBKDF2-SHA256 with 100k iterations for staff PIN hashing. Web Crypto in the Worker.
ADR-0014 — Per-staff permission overrides
Permissions resolve as COALESCE(staff_override, role_default). Per-staff overrides win over role defaults.
ADR-0015 — Idempotency keys on external writes
Every external write (Stripe, Twilio, etc.) uses an idempotency key. Retries reuse the same key.
ADR-0016 — Python ETL for AIM migration
Use Python (not JS) for the AIM SQL Server → Helm D1 migration scripts.
ADR-0017 — Mermaid for architecture diagrams
All architecture diagrams are Mermaid in the bible. No external diagramming tool.
ADR-0018 — Docusaurus for the bible
Use Docusaurus 3.x for this site. MDX docs, Mermaid, local search, Cloudflare Pages deploy.
ADR-0019 — In-situ editing as primary UX
In-situ editing is the primary path to changing visible UI. The Settings page is the secondary surface for non-visible configuration.
ADR-0020 — BC tax rules in code
Encode BC tax rules (GST 5% + PST 7%, bike-bundle exemption) in code, not as configurable shop settings.
ADR-0023 — Feature roadmap
Commit to the 15-feature v1+ roadmap as a canonical, ordered list, not an implicit one.
ADR-0024 — Serial numbers as first-class entities
Promote serial numbers from a text column on inventory to their own entity with a multi-event lifecycle, before Stage 3 slices build.
ADR-0025 — Federated multi-location
Chain capability via per-location deployments + aggregation, not via location columns on every table. Preserves the single-tenant commitment.
ADR-0026 — Google OAuth + device sessions (two-layer auth)
Layer 1 (Google OAuth → device cookie, 30-day sliding) gates the browser; Layer 2 (PIN → staff cookie, 60s idle) gates the till.
ADR-0027 — Local preflight over remote Kvick operator login
The need was code hygiene before deploy, not a remote multi-shop identity layer. Migration 039 added the identity tables; migration 040 dropped them; the local preflight toolchain replaces both.
ADR-0028 — Labels live in source, not a runtime override layer
Operator-visible labels are owned by public/index.html source; a persistent D1 override layer was considered and rejected.