# Fleet Ops

**A recruiter-ready operations platform for vehicle rental and service teams.**

[Open the live demo](http://192.168.10.150:1236) · no password required · choose **Highlights in 90 seconds** for the shortest tour.

Fleet Ops turns fragmented vehicle, booking and procedure data into one controlled operational workspace. It is a complete synthetic-data product demo: the company and records are fictional, while the workflows, persistence, validation, authorization, audit trail and integration boundaries are implemented.

![Fleet Ops engineering overview](frontend/public/og-fleet-ops.svg)

## The 90-second tour

1. Open **Highlights** from the login screen.
2. Follow a vehicle return from review to atomic commit, quality issue, outbox and correlated audit trace.
3. Compare and merge a duplicate customer with explicit human confirmation.
4. Ask the Knowledge Hub a damage question and inspect its cited procedure evidence.
5. Open **Engineering** for the architecture, reliability guarantees, test evidence and honest scope boundary.

## What makes it more than a mock-up

- **Transactional operations:** a return writes the inspection, vehicle/booking state, audit events and outbox record atomically. n8n downtime never rolls back the local business transaction.
- **Explainable data quality:** five persisted rule types, SLA deadlines, assignment, bulk queue controls and bounded resolution flows—not decorative warning cards.
- **Grounded knowledge:** the live deployment uses RAGcore; insufficient or unavailable evidence produces no invented answer. Citations and provider provenance remain inspectable.
- **Safe AI exposure:** four tenant-bound, service-authenticated, read-only Fleet Ops tools are published through ITWorx MCP Hub and audited with correlation IDs.
- **Operational reliability:** bounded retries, delivery leases, health/readiness, Prometheus metrics, Grafana, scheduled verified backups and graceful external-dependency degradation.
- **Real product ergonomics:** nl-BE, en-GB and fr-BE; responsive from 360 px; keyboard-accessible navigation; role-aware global search; route-level lazy loading; server-enforced permissions.

## Architecture

```mermaid
flowchart LR
    UI["React + TypeScript\nresponsive operations UI"] -->|session cookie| API["FastAPI\nbusiness rules + RBAC"]
    API --> DB[(PostgreSQL)]
    API -->|grounded retrieval| RAG[RAGcore]
    DB --> OUT["Transactional outbox"]
    OUT -->|bounded retry| N8N["Existing central n8n"]
    N8N -->|authenticated callback| API
    HUB["ITWorx MCP Hub"] -->|4 read-only tools| API
```

Fleet Ops owns operational truth. RAGcore owns retrieval, n8n performs post-commit orchestration, and MCP Hub owns tool transport/publication. Neither RAGcore nor MCP Hub accesses the Fleet Ops database directly. See [the as-built architecture](artifacts/evidence/architecture.md).

## Demonstrable scope

- dashboard, vehicle fleet, booking lifecycle and controlled returns;
- data-quality queue, assignment, review, merge and resolution;
- correlated human-readable audit history;
- cited Knowledge Hub with honest provider state;
- n8n delivery monitoring and manual retry;
- user administration, privacy export/anonymisation and retention guards;
- deterministic reset with 2 users, 180 customers, 50 vehicles, 254 bookings, 75 inspections, 40 maintenance records, 33 quality issues and 20 workflow runs.

This is deliberately not accounting, payments, a public reservation site, generic CRM, inventory, HR or an autonomous write agent.

## Stack

React, TypeScript, Vite, FastAPI, SQLAlchemy 2, PostgreSQL, Alembic, n8n, RAGcore, ITWorx MCP Hub, Docker Compose, Prometheus, Grafana and Playwright.

## Run locally

```bash
cp .env.example .env
make demo
```

- Web: `http://localhost:1228`
- API readiness: `http://localhost:8128/health/ready`
- Existing n8n server: configure `N8N_BASE_URL`; Fleet Ops does not create a second n8n instance.

The deterministic local knowledge provider supports clean-checkout acceptance without pretending to be the live RAGcore integration. Configuration is documented in `.env.example`; operations and recovery are in [docs/17-runbook.md](docs/17-runbook.md).

## Quality gates

```bash
make test    # isolated PostgreSQL backend suite
make lint    # Ruff + strict mypy
make e2e     # complete Playwright browser acceptance
cd frontend && npm run build
```

Current verified results and production evidence are recorded in [artifacts/evidence/final-summary.md](artifacts/evidence/final-summary.md) and [PROJECT_STATE.md](PROJECT_STATE.md).

## Repository map

- `backend/` — FastAPI domain, API, migrations and tests
- `frontend/` — React app and Playwright acceptance suite
- `contracts/` — OpenAPI, event and MCP contracts
- `knowledge/` — versioned fictional procedures
- `n8n/` — importable workflow definitions for the existing server
- `seed/` — deterministic synthetic dataset
- `docs/` — architecture, security, UX, testing and runbooks
- `artifacts/evidence/` — current acceptance evidence and screenshots

“MobilityOps” remains the repository/deployment identifier; **Fleet Ops** is the product name shown to users.