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, and docs/fleet-ops-final-localization/ for the follow-up correction round (remaining NL/FR translation gaps, centralized API-error localization, the time-dependent Europe/Brussels dashboard greeting).

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 workspaces with planning windows, location filters, service/next- booking context, operational ordering 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 with SLA deadlines, assignment, overdue/bulk queue controls, bounded resolution flows and 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;
four canonical n8n workflows: return processing, scheduled data-quality scanning, RAGcore procedure sync and centralized workflow-error handling, with explicit heartbeat evidence and crash-recoverable outbox delivery leases;
four read-only MCP tools through ITWorx MCP Hub;
deterministic demo reset and five-minute showcase.
audited operational user creation, role/name editing, password reset and activation.

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 live deployment uses KNOWLEDGE_PROVIDER=ragcore. Readiness and real grounded retrieval are verified end to end; when RAGcore's generated-answer endpoint is unavailable, Fleet Ops falls back only to cited extractive search results and never invents an answer. The deterministic demo provider remains available for clean-checkout acceptance and local development.
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 actually wired into Settings and reported honestly by the integration-status endpoint (evidence-based: real tool-call audit history, not just the flag). The Fleet Ops connector is confirmed live in the ITWorx MCP Hub's own production deployment (Tower), with a real contract fix already applied there (vehicle.get's wire parameter normalized to vehicleRef).

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

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 readiness: http://localhost:8128/health/ready (liveness: /health/live)
n8n: http://localhost:5678

All defaults are configurable via .env (see .env.example).

Quality gates

make test    # backend: isolated PostgreSQL Compose project; never the live database
make lint    # backend: ruff + mypy (strict, zero errors)
make e2e     # frontend: complete Playwright acceptance (live stack required)

Frontend build/typecheck: cd frontend && npm run build (tsc -b && vite build).

README.md Unescape Escape

Fleet Ops