# Fleet Ops **Connected operations for vehicle rental and service teams.** Fleet Ops is a working proof of concept for a fictitious mobility company. It combines vehicle and booking operations, a controlled vehicle-return workflow, data-quality review, RAGcore-backed internal knowledge, n8n orchestration and read-only tools published through ITWorx MCP Hub. **Naming:** "Fleet Ops" is the product's visible name everywhere in the UI, the demo knowledge base, and this documentation. "MobilityOps" remains the technical identifier only — the repository name, local directory, package/module names, Docker Compose project, deployment directory, and database names. The UI is fully trilingual (nl-BE default, en-GB, fr-BE); see `docs/fleet-ops-correction/` for the localization architecture, the vehicle-status decision table, and the correction evidence. The web application uses the premium responsive **Control Rail** interface: a compact operations-first workspace with persisted readiness metrics, evidence-led exceptions, review-before-commit return handling and mobile navigation designed down to 390 px. See `docs/design/design-directions.md` and `docs/design/implementation-validation.md` for the design decision and visual evidence. All people, companies, vehicles, bookings and documents are synthetic. The workflows, validation, integrations, audit logging and access boundaries are intended to be real. ## Demo The demo presents itself as **Northstar Mobility**, a fictitious Belgian camper/van rental company — the login screen, a permanent "Synthetische demo" indicator, an in-app guided tour (Demo Guide), a curated `/scenarios` overview, and an "Over deze demo" page all make the fictional context, synthetic-data status, and real-vs-simulated boundaries explicit without any verbal explanation. See `docs/demo-release/` for the full demo concept, the five named scenarios, the seed/date-anchoring strategy, the guided-tour design, and the operational runbook (5-minute and 10-minute demo flows, reset, redeploy, rollback). ## Scope The PoC implements: - operations dashboard with a truthful aggregate n8n/MCP integration-status card; - vehicle and booking views with working search, filters and pagination; - server-backed session lifecycle (refresh-safe, central 401 handling); - a role matrix enforced server-side and mirrored in the UI (see `docs/12-security-and-audit.md`); - vehicle return capture → authoritative server-evaluated review → commit → result; - five deterministic data-quality checks, each with a bounded resolution flow, plus a manual scan action; - human review and customer merge; - audit trail with human-readable before/after evidence and safe entity links; - role-aware global search across vehicles, bookings and (Operations Manager) issues; - safe, confirmed demo reset; - RAGcore-backed knowledge assistant with citations; - two n8n workflows: return processing, and a scheduled data-quality scan with crash-recoverable outbox delivery leases; - four read-only MCP tools through ITWorx MCP Hub; - deterministic demo reset and five-minute showcase. It is not an ERP, CRM, accounting package, public booking site, payment system or autonomous agent. ## Integration status - **n8n**: fully implemented and verified against a real n8n instance, including degraded mode (n8n stopped mid-flow → return still commits, event stays `pending` with backoff, self-heals once n8n returns), the failed-delivery manual-retry path, stale-delivery-lease recovery after a simulated crash, and a second (scheduled quality-scan) workflow live-verified end to end against a real n8n instance. `GET /api/v1/integrations/status` reports a truthful aggregate state from outbox delivery counts, not just the most recent event. - **RAGcore**: the demo `KnowledgeProvider` (deterministic TF-IDF extractive retrieval over the local procedure documents) is what satisfies the knowledge-assistant acceptance criteria and is fully verified. A `RAGcoreKnowledgeProvider` HTTP adapter is implemented and unit-tested, including its unavailable-degradation path, but was never exercised against a live RAGcore instance in this environment. - **ITWorx MCP Hub**: the four read-only provider endpoints are implemented, tested, and directly `curl`-verified with correct auth enforcement and audit logging. `MCP_HUB_REGISTRATION_ENABLED` is now actually wired into `Settings` (it was previously declared in `.env.example` but silently dropped) and reported honestly by the integration-status endpoint. No live Hub instance was reachable in this environment to verify an actual Hub round trip. See `artifacts/functional-completion/final-summary.md` for the functional-completion audit evidence (supersedes the design-validation summary below for integration status), and `artifacts/final-acceptance/summary.md` for the original M0–M7 acceptance evidence. ## Repository map - `CLAUDE.md` — binding implementation rules. - `MASTER_BUILD_PROMPT.md` — prompt to start an autonomous Claude run. - `PROJECT_STATE.md` — short persistent project memory. - `docs/` — product, architecture, UX and acceptance specification. - `contracts/` — OpenAPI, event and MCP contracts. - `knowledge/` — fictitious source documents for the MobilityOps RAGcore workspace. - `seed/` — deterministic synthetic dataset and generator. - `n8n/` — importable workflow definitions. - `backend/` — FastAPI/SQLAlchemy/Alembic API. - `frontend/` — React/TypeScript/Vite web app, including the Playwright end-to-end suite (`frontend/e2e/`). - `artifacts/evidence/` — final acceptance evidence (screenshots, architecture, `final-summary.md`). - `artifacts/design-validation/` — baseline audit, Stitch direction references and implemented responsive captures. - `docs/functional-completion/` — the functional-completion audit and pre-work server baseline. - `artifacts/functional-completion/` — functional-completion acceptance evidence. - `docs/demo-release/` — demo concept, scenarios, seed/date-anchoring strategy, guided tour, and runbook. - `artifacts/demo-release/` — demo-productization acceptance evidence. ## Quickstart ```bash cp .env.example .env make demo ``` This builds and starts the full stack (migrations run automatically) and loads the deterministic demo dataset. See `docs/17-runbook.md` for the one-time n8n workflow setup required for the automation demo, and the full operational runbook. Endpoints: - Web: `http://localhost:1228` - API health: `http://localhost:8128/health` - n8n: `http://localhost:5678` All defaults are configurable via `.env` (see `.env.example`). ## Quality gates ```bash make test # backend: pytest (151 tests) make lint # backend: ruff + mypy (strict, zero errors) make e2e # frontend: Playwright end-to-end (113 tests, live stack required) ``` Frontend build/typecheck: `cd frontend && npm run build` (`tsc -b && vite build`).