MobilityOps/README.md

# 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, 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

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

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

## Quality gates

```bash
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`).