Skip to main content

C4 — Context diagram

The widest view. Who uses the Hub, and which external systems the Hub talks to.

Drafted from planning · v0.1

Boundaries​

Inside the system context: the the kvick-bike Worker, the per-shop D1 database, the per-shop R2 bucket, the bible RAG corpus.

Outside: every external SaaS the Hub depends on. The shop's bank (Stripe wires money there), Cloudflare's own infrastructure (Workers, D1, R2), the operator's hardware (terminal, printer, scanner, drawer).

People (actors)​

ActorWhat they doWhat they see
Shop ownerConfigures shop, hires/fires staff, sets prices, reviews moneyAll screens. Owner role grants all 10 tabs.
Sales staffRings sales, takes phone calls, attaches customers, processes returnsSales + Customers + Inventory (read-only mostly). Sales role.
MechanicWorks the service queue, adds parts/labour to tickets, marks tickets readyToday + Service + Customers + Inventory. Mechanic role.
JuniorCash register only; basic customer lookup. No money-altering actions.Today + Sales + Customers. Junior role.
End customerDrops off a bike, picks one up, buys parts, books a rentalPublic marketing site. Does not log in to the Hub directly.

The role + permission system is per-shop (no shared identity across shops) — see security model.

External systems​

Stripe — card processing + subscriptions​

The shop's own Stripe account, connected via Stripe Connect (Standard accounts). In-shop card via Stripe Terminal hardware; the Hub subscription (Kvick → shop) goes through a separate Stripe customer.

Twilio — outbound SMS​

One Kvick-owned account, per-shop sub-accounts. Use cases: "your bike is ready," "your appointment is tomorrow," "we received your trade-in offer," "marketing opt-in confirmations." Two-way conversational SMS is on the roadmap but not in scope today.

Anthropic Claude API — AI Support bubble + corpus indexing​

RAG against this bible + the shop's own D1 schema + the operator's conversation history. The Support bubble is conversational; under the hood, structured queries to D1 run alongside the chat for grounded answers. See AI integration and slice 11.

Google Business Profile (GBP) API — reviews + hours​

Read reviews, post replies, sync shop hours from shop_config. OAuth flow against the shop owner's Google account. Webhook-driven for new reviews.

Meta Graph API — Instagram / Facebook​

Cross-post shop content (new arrivals, sales, events). Read engagement metrics for the dashboard. Per-shop OAuth.

Vendor APIs — Quality Bicycle Products (QBP), Shimano, others​

B2B procurement: auto-PO from low-stock alerts, real-time wholesale stock checks. Per-shop credentials. Most shops start without these wired; they're an add-on for shops that want them.

Resend / Postmark — transactional email​

Receipt emails, password resets, weekly summary emails to owners. Choice of vendor TBD; current preference Resend for deliverability + developer experience.

What's deliberately NOT in the system context​

  • Accounting (Quickbooks Online, Xero) — exports only, no real-time integration. Daily/weekly CSV/JSON dump for the shop's accountant.
  • HR / payroll — out of scope. the Hub tracks hourly wages for cost-of-service reporting, but does not run payroll.
  • Inventory marketplace — the Hub doesn't expose a shop's inventory to a multi-shop marketplace. Each shop's data is theirs.
  • Multi-shop reporting — when Kvick has 50+ shops, aggregate analytics across them (with consent) inform future product features. Today: out of scope.

See also​