# Demo concept

## The fictional problem

**Northstar Mobility** is a fictional Belgian camper/van rental company with roughly 50
vehicles, one main location, a rental team, an operations manager, and a small workshop.
Northstar Mobility does not exist — this name and every customer, vehicle, booking and
procedure in the demo are synthetic. Before MobilityOps, Northstar Mobility's bookings,
returns, customer records and maintenance history lived in spreadsheets and verbal
hand-offs, so problems (duplicate customers, incorrect odometer readings, double-booked
vehicles) only surfaced late, after they had already caused friction. MobilityOps shows
how one connected system detects these problems early and lets an Operations Manager
resolve them under audit, with automation handling the routine follow-up.

## Target audience

Anyone evaluating how MobilityOps approaches operational data-quality and hand-off
problems for a small rental fleet: Operations Managers, Rental Employees, and reviewers
assessing the approach. No account setup or backend knowledge is required to start —
the login screen explains the fictional context and offers a guided path.

## Demo scope

This is a focused proof of concept, not a full ERP. In scope: vehicle and booking
management, return processing with server-side evaluation, five data-quality detection
rules each with one bounded resolution flow, a full audit trail, and orchestration via a
real n8n instance. Explicitly out of scope: accounting, payments, public reservations, a
generic CRM, inventory, HR, a second RAG stack, or autonomous write actions from any
external tool.

## What's really implemented

All of the following is functional code, not a mockup or hardcoded screen:

- Role-based authentication and server-verified sessions (Operations Manager, Rental
  Employee), enforced both server-side and in the frontend's navigation/route guards.
- Vehicle and booking management, with return preview/commit sharing one authoritative
  evaluation function so they can never drift.
- Five data-quality rules (possible duplicate customer, missing required field, odometer
  regression, booking overlap, vehicle status conflict), each with exactly one bounded,
  audited resolution endpoint.
- A full audit trail with before/after state, actor, correlation IDs, and a
  "view related events" link reusing that correlation.
- Reliable outbox-based delivery to a real n8n instance, with bounded retries and
  stale-delivery recovery.
- Docker Compose deployment and an automated test suite (backend pytest, Ruff, mypy,
  and a full Playwright end-to-end suite covering the demo experience itself).
- A demo manifest (`GET /api/v1/demo/manifest`) as the single source of truth for the
  demo's identity, synthetic-data status, reset state, scenario readiness, and honest
  per-integration labels — the frontend never hardcodes what mode it's in.

## What's synthetic

The organisation, all customers, vehicles, bookings, maintenance history, the knowledge
base's procedures, and the five prepared demo scenarios are entirely fictional. No data
refers to a real person, vehicle, or company. Every seeded email uses the `.test`
reserved domain. See [`demo-data.md`](demo-data.md) for exactly how this data is
generated and kept fresh across resets.

## What's not yet live-connected

- **RAGcore**: not connected. The knowledge assistant uses a local, deterministic
  keyword-matching "demo knowledge base" built from five procedure documents, honestly
  labelled as such everywhere in the UI (never presented as RAGcore). A
  `RAGcoreKnowledgeProvider` HTTP adapter exists and is unit-tested, ready to take over
  the same interface once a real RAGcore backend is available — swapping providers is a
  configuration change (`KNOWLEDGE_PROVIDER`), not a UI change.
- **ITWorx MCP Hub**: not connected. Registration is disabled by default
  (`MCP_HUB_REGISTRATION_ENABLED=false`) and the UI always shows "Not connected" —
  never a fabricated successful registration.

## Where to go next

- [`demo-scenarios.md`](demo-scenarios.md) — the five guided scenarios and their fixed records.
- [`demo-data.md`](demo-data.md) — seed strategy and date-anchoring.
- [`demo-guide.md`](demo-guide.md) — the in-app 8-step guided tour.
- [`demo-runbook.md`](demo-runbook.md) — how to run, reset, and redeploy the demo.