Fleet Ops

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

Try it in two commands (cp .env.example .env && make demo, then open http://localhost:1228) · no password required · choose Highlights in 90 seconds for the shortest tour. The reference deployment runs on a private LAN (see deploy/unraid/README.md); ask for a link if you want the hosted version.

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.

The 90-second tour

Open Highlights from the login screen.
Follow a vehicle return from review to atomic commit, quality issue, outbox and correlated audit trace.
Compare and merge a duplicate customer with explicit human confirmation.
Ask the Knowledge Hub a damage question and inspect its cited procedure evidence.
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

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.

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

cp .env.example .env
make demo

Web: http://localhost:1228
API readiness: http://localhost:8128/health/ready
Existing n8n server: point N8N_WEBHOOK_URL at its return-processing webhook (see .env.example). The bundled n8n service in compose.yaml is a local fallback only; production reuses the server's central n8n (compose.unraid.yaml disables the bundled one).

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.

Quality gates

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

Release-scoped results and production evidence are recorded in artifacts/final-acceptance/summary.md; older milestone evidence remains explicitly historical. PROJECT_STATE.md records the commands and exact deployment revision.

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/ — dated, release-scoped acceptance evidence and screenshots

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

5.5 KiB Raw Blame History