M29: polish recruiter engineering story
This commit is contained in:
NuklearRabbit
@@ -1,136 +1,94 @@
|
||||
# Fleet Ops
|
||||
|
||||
**Connected operations for vehicle rental and service teams.**
|
||||
**A recruiter-ready operations platform 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.
|
||||
[Open the live demo](http://192.168.10.150:1236) · no password required · choose **Highlights in 90 seconds** for the shortest tour.
|
||||
|
||||
**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).
|
||||
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 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.
|
||||
## The 90-second tour
|
||||
|
||||
## Demo
|
||||
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.
|
||||
|
||||
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).
|
||||
## What makes it more than a mock-up
|
||||
|
||||
## Scope
|
||||
- **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.
|
||||
|
||||
The PoC implements:
|
||||
## Architecture
|
||||
|
||||
- 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.
|
||||
```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
|
||||
```
|
||||
|
||||
It is not an ERP, CRM, accounting package, public booking site, payment system or autonomous agent.
|
||||
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).
|
||||
|
||||
## Integration status
|
||||
## Demonstrable scope
|
||||
|
||||
- **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`).
|
||||
- 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.
|
||||
|
||||
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.
|
||||
This is deliberately not accounting, payments, a public reservation site, generic CRM, inventory, HR or an autonomous write agent.
|
||||
|
||||
## Repository map
|
||||
## Stack
|
||||
|
||||
- `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.
|
||||
React, TypeScript, Vite, FastAPI, SQLAlchemy 2, PostgreSQL, Alembic, n8n, RAGcore, ITWorx MCP Hub, Docker Compose, Prometheus, Grafana and Playwright.
|
||||
|
||||
## Quickstart
|
||||
## Run locally
|
||||
|
||||
```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`
|
||||
- API readiness: `http://localhost:8128/health/ready`
|
||||
- Existing n8n server: configure `N8N_BASE_URL`; Fleet Ops does not create a second n8n instance.
|
||||
|
||||
All defaults are configurable via `.env` (see `.env.example`).
|
||||
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 # 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)
|
||||
make test # isolated PostgreSQL backend suite
|
||||
make lint # Ruff + strict mypy
|
||||
make e2e # complete Playwright browser acceptance
|
||||
cd frontend && npm run build
|
||||
```
|
||||
|
||||
Frontend build/typecheck: `cd frontend && npm run build` (`tsc -b && vite 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.
|
||||
|
||||
Reference in New Issue
Block a user