Skip to main content

Data flow diagrams

Sequence diagrams for the flows that span multiple components. The C4 Component diagram shows what exists; these show how the pieces talk to each other for specific operations.

Drafted from planning · v0.1

1. In-shop sale (cash or card)​

The most-traveled path in the system. Operator scans/types items, customer pays, receipt prints, audit row lands.

Failure modes:

  • Stripe declines — transactions.status stays pending, no inventory decrement, no audit row. UI offers retry or alternate payment.
  • Stripe succeeds but D1 update fails — the idempotency key on the next attempt prevents double-charging; daily cron reconciliation flags the orphan PaymentIntent.
  • R2 receipt-write fails — non-blocking; receipt is regenerated on demand from the transaction row. UI does not block on R2.

2. Service ticket lifecycle (drop-off → ready → picked up)​

Spans days, multiple operators, optional Twilio touchpoints.

Cross-references:

3. Rental booking (online → kiosk pickup → return)​

A customer books online for tomorrow. The next morning they walk in, the kiosk scan confirms, the bike rolls out. They return it that evening.

4. AI Support bubble query (RAG against bible + shop D1)​

Operator clicks the AI bubble bottom-right and asks a question. Helm answers using the bible, the operator's recent context (current screen/customer/ticket), and structured queries against D1.

Privacy notes:

  • If the customer's record has ai_optout = 1, the structured grounding payload skips their identifying fields and the conversation is logged with customer_id = NULL.
  • See AI integration, data ownership, slice 11.

What these diagrams deliberately hide​

  • Auth resolution on every Worker call — assumed to have happened. See security model.
  • D1 read-replication latency — D1 is single-writer per database; reads hit the closest replica. Sub-50ms typically.
  • Logging / metrics — every Worker request emits a structured log line; not shown above to keep diagrams readable.
  • Error UI — the success path is documented; failure paths are described in prose under each diagram.

See also​