Skip to main content

KVICK.BIKE Bible

Public · comprehensive · successional. This is the whole picture — every architectural decision, every operational doctrine, every domain rule, every trade-off Kvick made along the way. Nothing's hidden in a private wiki; nothing's withheld for an internal tier. If a shop, an operator, a developer, an auditor, or a successor needs to understand how the system works (or why it works that way), the answer is in here.

This Bible covers the clean-room bike-vertical Hub — the kvick-bike Worker that ships at kvick-bike.solitary-poetry-5fcc.workers.dev. One Worker, one D1, three strata, modular bricks.

This Bible is one of many

Every KVICK customer's deployment ships with its own Bible, public at its own URL. The shared canon (foundation, principles, decisions, domain) is identical across every bike-shop instance; each customer's Bible additionally records the deviations they chose. The Bible is the spec the shop bought into, and the record of how their copy diverged. See Per-build pattern below.

Who reads this​

Shop owners weighing a switchStart with What is Kvick?, the Doctrine and Customer Compact — they say plainly what you're buying into. The Business model page covers price + terms.
Operators + staffThe Principles section answers most "why does it do this?" questions. The Domain section maps the entities (customers, bikes, tickets, transactions) and lifecycles you'll work with daily.
Developers joining coldSubstrate Line → Three Scenarios → Slice overview, then the slice you're touching. Local setup is in Runbooks.
AI agents (the off-app auditor, the in-Hub Support bubble when it lands)The corpus is structured for retrieval; the conformance suite reads it as the canon to grade against.
Partners, auditors, successorsWhatever you need to know, the Bible has the full text. ADRs (Decisions) capture the reasoning behind every load-bearing choice.
Anyone curiousWelcome. Read freely.
Build it as we code

This Bible grows page-by-page as code lands. No history-book content. No planning documents that don't reflect shipped state. If a page can't be deleted without losing load-bearing information, it earns its keep. If it can, it goes.

The discipline is the review-and-update loop: every meaningful commit on the operator Hub either updates an existing page or earns a new one in the same commit window.

Why a per-build Bible​

Every KVICK build ships with its own Bible — public at its own URL. The reasons:

  1. It's the spec the shop bought. The vertical canon (the bike-shop doctrine, the architectural choices, the domain model) is identical across every bike-shop instance. Each customer's Bible additionally records the L3 deviations they chose — "our walk-in deposit is 25%, not the canon 20%" lives in their Bible, signed by them.
  2. It substitutes for institutional memory. Twelve months from now, someone — a new owner, a new developer, an AI agent, the original team — needs to know why this shop's deposit rule is what it is. The Bible is the answer.
  3. It's the input to the off-app auditor. Per the conformance-suite doctrine, the auditor grades the running system against the canon — not against itself. The Bible is the canon's human-readable face; the Process Library (BIKE.L<n>-NNNN designations + realizes_links(spec→binding) edges) is its machine-readable face. Same canon, two surfaces.
  4. It's a public-trust instrument. Customers can read the Bible before signing. They see the audit-chain commitment, the data ownership ADR, the single-tenant guarantee, the privacy policy. The Bible's public surface is part of how Kvick earns trust.

What's here today​

120 pages spanning the full vertical canon — every doctrine that shapes the bike-shop Hub, every architectural decision, every domain entity and lifecycle. Browse by category:

  • Foundation — the load-bearing doctrine (read this first)
  • Overview — what Kvick is, business model, customer + market, tech stack, roadmap
  • Principles — the "why does it do this?" answers
  • Architecture — the system's mechanics
  • Decisions — the ADRs explaining every load-bearing choice
  • Domain — entities, lifecycles, slices (the bike-shop model)
  • Runbooks — operational playbooks
  • Contributing — engineering discipline
  • Playbooks — situational scripts (tax jurisdiction, customer erasure, Stripe dispute, data export)
  • Reference — tables and registries

Pages on the clean-room implementation substrate (three strata, the modular brick pattern, per-module specs) land as those modules ship — Customers is the first.

How this Bible is built + deployed​

This Bible is a standalone Cloudflare Pages deployment (source: KVICKADMIN/KVICK.BIKE.BIBLE). It owns its own public URL end-to-end; the kvick-bike Worker (the operator app) links to it from the user-menu but serves none of the content. Decoupled by construction — Bible edits never touch the Hub's deploy; Hub deploys never touch the Bible.

The source is open. The build is reproducible (npm install && npm run build). The deploy is one command (npx wrangler pages deploy). The discipline is documented in Update Bible and Documentation maintenance.

See also​