Files

T

NuklearRabbit 38f654b97a docs(demo): add demo concept, scenarios, data, guide and runbook docs

Documents the demo-productization work from this branch: the Northstar
Mobility fictional concept and scope, the five named scenarios and their
fixed records, the seed/date-anchoring strategy (including the real bug
it fixed), the in-app Demo Guide's design and the English-suggested-
questions decision, and an operational runbook covering 5/10-minute demo
flows, reset, Unraid redeploy and rollback. Updates README with current
test counts and pointers to the new docs.

2026-08-03 15:24:35 +02:00

3.9 KiB

Raw Blame History

Demo scenarios

Five fixed scenarios are surfaced at /scenarios and via GET /api/v1/demo/manifest's scenarios array, which derives each scenario's ready/blocked_reason from the actual underlying records — never hardcoded. All five are re-findable, using the same public references, after every demo reset (see demo-data.md).

1 — Odometer regression on return

Fixed records: booking BK-DEMO-RETURN on vehicle MO-024.
Role: Rental Employee or Operations Manager.
Problem demonstrated: a return is submitted with an odometer reading lower than the vehicle's canonical reading — usually a data-entry mistake or a return logged against the wrong vehicle.
Flow: open the booking. The return form is pre-filled with a suspicious reading below MO-024's canonical odometer (the demo never asks a visitor to invent one), with a callout explaining why. Review the server-evaluated preview, then confirm. The canonical odometer is never silently lowered; a data-quality issue is opened automatically and the outcome is queued for delivery to n8n.
Continue: the result panel links to the vehicle, automation status, and audit trail, plus (inside the guided tour) a "Ga verder met de demo" button.

2 — Possible duplicate customer

Fixed records: customers CUS-0012 and CUS-0178 (same email/phone), issue DQ-DEMO-DUPLICATE.
Role: Operations Manager (merge is a bounded, audited action).
Problem demonstrated: two customer profiles that are very likely the same person, registered twice — a risk for split booking history and duplicate contact.
Flow: open the issue, compare both profiles field by field, choose which survives, and merge. The losing profile becomes a tombstone linked to the survivor; its bookings are rewired. The result is recorded in the audit trail.

3 — Overlapping bookings

Fixed records: vehicle MO-016, bookings BK-DEMO-OVERLAP-A/BK-DEMO-OVERLAP-B, issue DQ-DEMO-OVERLAP.
Role: Operations Manager.
Problem demonstrated: the same vehicle committed to two overlapping reservations — a legacy-import-style conflict that a normal booking command would reject outright.
Flow: open the issue, choose which of the two bookings to block; the other keeps its current status.

4 — Failed automation, retried

Fixed record: a seeded outbox event (00000000-0000-4000-8000-000000000020, BK-H-0020) that is durably failed immediately after every reset — a safe, simulated connection error, not a deliberately destabilised n8n configuration.
Role: Operations Manager.
Problem demonstrated: bounded retries and visible failure/recovery state for workflow delivery, rather than a silent drop.
Flow: open Automation, filter to failed deliveries, retry the event; it moves out of the failed filter once delivered.

5 — Grounded procedure question

Role: Rental Employee or Operations Manager.
Problem demonstrated: an operational question gets an answer with a citation from the demo knowledge base — or an honest "insufficient evidence" if nothing indexed answers it — never an invented answer.
Flow: open Knowledge, click one of the suggested questions (English, matching the indexed procedure content — see the note in demo-guide.md about why suggested questions stay in English even though the rest of the demo narrates in Dutch), and inspect the cited source and evidence state.

A sixth scenario exists but isn't one of the five requested

docs/13-seed-and-demo-scenarios.md's S3 ("missing inspection before next booking", vehicle MO-031) is also seeded and shows up in the attention queue; it isn't surfaced on /scenarios because the brief names five specific scenarios, but it remains available for anyone exploring the attention queue directly.

3.9 KiB Raw Blame History