C4 — Context
the Hub in its environment. The actors and systems the Hub interacts with.
Data flow diagrams
Sequence diagrams for the four most important cross-component flows.
Deployment topology
How the Hub is deployed per-shop, how shops are isolated, how this scales from 1 to 50 shops.
Security model
Authentication, authorization, session management, secrets, audit trail.
AI integration
How the Hub uses Claude — the Support bubble, RAG against the bible, conversation memory, the budget.
Offline architecture
Store-and-forward POS — what works when the shop's internet drops, how writes queue, how reconnect drains them.
Build versioning
Every build of the Worker has a frozen version string. Every audit row records the build that produced it. Forensic queries answer "which build was running when this happened" from the chain alone.
Global search palette
A single Cmd-K-style overlay that searches across customers, inventory, and service tickets in one query, returning typed + grouped results.
Search engine (FTS5)
Best-in-class text search — SQLite FTS5 per domain, BM25 ranking, synonyms, click telemetry, planned trigram + custom ranker. One portable engine, four domains.
Data-consistency layers
A layered story for "your write didn't collide with someone else's write" + "your screen shows fresh data without you asking." Layer 1 (optimistic locking) and Layer 4 (reactive query framework) live; Layers 2-3 planned.
Integrations
How the Hub connects to third-party services — GBP (manual config today, OAuth later), owner-defined custom integrations with five auth types, and the production secret-store pattern.
Process Library
The D1-backed catalogue of shop workflows — three-layer model (Code / Vertical / SME), Store action vs Software process, the Pending/Programmed/Needs-code review pipeline, the Process Map, and the dormant Interpretation Engine.
The Three Scenarios
How the BWS machine produces a new customer in an existing vertical (Scenario 1), a new vertical with maximum reuse (Scenario 2), and a new vertical canon-led before the first client (Scenario 3). Each has its own layer arrangement, gap-worked, and definition-of-done.
Scaffolding chassis
Three-mode help layer (beginner / intermediate / expert) with per-feature decay. Tooltips fade as the operator gets comfortable with a feature and restore on long inactivity. Expertise lives at the feature level, not at the staff level.
Multi-user realtime
How a write on terminal A surfaces on terminal B in sub-second time. parked_sales server-side substrate (migration 062), topic-invalidation broadcasts, the forward-bridge that maps topic events to the legacy custom-event renderers. Shipped v0.6.112.
Audit narrator + ticker tape
Every mutation gets a plain-English sentence. The narrator is a deterministic verb/lexicon library keyed by event_type; the shell footer is a 25-px ticker tape that scrolls the last few. Verbose peek on hover. Click-to-open was tried and pulled — the ticker is glanceable, not interactive.
Backorder → Bucket flow
A zero-stock cart line no longer blocks the sale. It rings through with a red backorder N annotation; on Charge, the shortfall auto-drops into the Purchases Bucket with the customer's name attached. One flow across three modules — Sales rings, Inventory adjusts (or the ring stays as a special order), Purchases sees "Awaiting order · for [Customer]" on the next Bucket refresh.
Scaffolding tooltips
Per-staff, per-feature hover hints that decay with use. The register teaches itself. First visit shows every hint; by the tenth usage the hint has faded; miss a feature for weeks and the hint comes back to re-teach. Every hint is a row in feature_registry; every staffer has their own decay state.
Keep-mounted SPA navigation
Modules mount once and persist across tab switches. The Core router toggles visibility, never tears the module down. A module's client IIFE runs once per session, not once per visit.
Receipt engine
One receipt everywhere. The same code path prints a thermal cash receipt, a full-page Letter estimate, a refund slip, a layaway deposit stub, a special-order pickup ticket. Post-sale prompt asks Print / Email-soon / No receipt; Enter confirms Print; localStorage remembers an operator who wants always-auto-print.
Conformance suite — off-app QA
How the Hub is QA'd. Code-blind off-app sweep via Cowork plugin; the Process Library canon is the spec the sweep checks against.
Core keyboard layer
One Kernel primitive owns keyboard behaviour across every module. LIFO ESC stack — Escape dismisses the topmost open popup / cancels the active edit / clears the till, in that order, one press at a time. Shortcut registry feeds a "?" cheat-sheet.
Scaffolding (Beginner / Intermediate / Expert)
Chassis-level UI scaffolding system. Three modes that govern help density, with per-feature decay so expertise lives at the feature level, not the user level.
Module — scaffolding
Service surface, route table, schema, and API contracts for the scaffolding subsystem.