96 lines
5.6 KiB
Markdown
96 lines
5.6 KiB
Markdown
# 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](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
|
|
|
|
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: 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](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
|
|
python scripts/run-readonly-load-smoke.py # while the demo stack is running
|
|
```
|
|
|
|
Release-scoped results and production evidence are recorded in [artifacts/final-acceptance/summary.md](artifacts/final-acceptance/summary.md); older milestone evidence remains explicitly historical. [PROJECT_STATE.md](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.
|