Skip to main content

The Bespoke Web System

KVICK is a machine that builds bespoke commercial systems. The Hub is the first thing the machine built; the bike-shop industry is the first vertical the Hub was shaped for. Everything built for that vertical is meant to be reused, recycled, and reinvented for the next one.

A Bespoke Web System (BWS) is the anatomy this machine produces. Fix the anatomy in your head before reading anything else in this bible, because a build session that gets it wrong builds the wrong thing.

A BWS is one per-customer stack, two surfaces​

A Bespoke Web System is one per-customer stack:

  • One Cloudflare Worker (the src/index.js you see in this repo)
  • One D1 database (per-shop SQLite)
  • One R2 bucket (per-shop asset storage)

Single-tenant per shop, per ADR-0003. Nothing is shared at runtime — only the template that the shop's deployment branch was cut from. One stack per customer is what makes per-shop drift safe; one shop's divergence cannot corrupt another's, because they don't share a database.

That one stack exposes two surfaces:

1. The Hub — the private operator system (primary)​

This is where the business is run and where the data is controlled. The Hub is primary. The Process Library and its L1/L2/L3 layers live here. When anything in this bible talks about building, harvesting, canon, and gaps, it is talking about the Hub.

2. The public-facing website — the customer surface​

The customer-facing site. It is controlled and fed by the Hub, live, from the same data store. It is not a separate artifact, not a separate repo, not a separate database, and there is no build-and-publish step that copies data out to it.

The feed is a shared data layer, not a publish​

This is the part that gets built wrong if you don't read it carefully.

The public site and the Hub are two request paths into the same Worker and the same D1. The canonical example is the rental flow (data-flow diagrams):

  1. A customer books a rental on the public site.
  2. The booking POSTs to the same Worker the operator's staff use.
  3. The Worker writes a rentals row to the one D1.
  4. The operator sees that booking in the Hub the next morning by reading the same table.

The customer's action and the operator's view are the same data, because there is only one store. The "publish" step doesn't exist; the public site reads (and sometimes writes) the per-customer D1 directly through the Worker. A change the operator makes in the Hub is reflected on the public site with no rebuild — it's the same data.

Content that has a draft/published distinction (per the content-versioning layer) handles that as row state within the one store — a draft row vs a published row — not as a second system to publish to.

What this means for a build session​

This is the part that's load-bearing. Get it wrong once and you rebuild a separate static site you don't need.

  • Never scaffold the public site as a standalone static site with its own pipeline. That was the dead tradesperson-product pattern. The public site is an output of the Hub's data.
  • No separate repo for the public site. The Worker that serves /api/* and /admin/* also serves the public surface routes (/, /rentals, /services, /products). One codebase, one deploy.
  • No separate database for "public content." Draft / published / archived are row states on the existing tables. There is no cms_* or wagtail_* shadow schema.
  • Quality bar for what the public surface serves lives in Public Surface Standards — that bar is universal across verticals.
  • Structure and content of the public surface come from the Hub and the vertical, not from a separate authoring spec. A bike-vertical site exposes bikes and service tickets; a future vertical's site exposes whatever the vertical's L2 canon and L3 SME knowledge describes.

So everywhere else in this bible, "the system," "the code," and "L1" mean the Hub. The public website comes along as the Hub's fed, controlled, customer-facing surface.

Why this anatomy​

Two surfaces with one store is what makes the BWS bespoke and coherent at the same time:

  • Bespoke because each customer's stack is single-tenant; their data shape, their config, their drift is theirs alone.
  • Coherent because the same customers row that the public site reads when authenticating an online order is the row the operator sees when the customer walks into the shop. No reconciliation step. No two-way sync. No staleness.

The alternative — a separate public site with its own database that the Hub periodically syncs to — was tried in the discontinued tradesperson product and produced exactly the failure modes you would expect: data divergence, two sets of auth credentials, two sets of audit gaps, two deploy pipelines, two debugging stories. The BWS doctrine rules that pattern out.

See also​

  • Three Scenarios — the three things the machine produces (new customer, new vertical reuse-led, new vertical canon-led)
  • The Substrate Line — what's portable across verticals, what's vertical tissue
  • Process Library — the three-layer model (L1=code, L2=vertical, L3=SME) the machine uses to address reuse
  • Single-tenant per shop — the discipline that makes per-shop drift safe
  • What is the Hub? — the operator-facing surface of the BWS
  • Public Surface Standards — the quality bar for the public-facing surface