NuklearRabbitandClaude Sonnet 5
34df66d28c
GUI: dashboard Attention Queue presents a curated severity mix instead of pure severity-sort (grouped Now/Today/Later headers); Today's Movements seed data curated so a fresh reset shows a credible day (2+ departures, 2+ returns), with a new seed-integrity test; About Demo restructured into a compact grid with progressive disclosure for technical sections; Duplicate Merge shows match/conflict counts, hides matching fields by default, and previews the final merged record before confirmation. Repo hygiene: removed a stray empty `backend;C` directory and an untracked 31MB zip export; `.gitignore` now excludes future archive exports. n8n: fixed invalid JSON (a missing `},` between two node objects) in the committed `fleet-ops-vehicle-return.json` -- the file could not be parsed. Live-validated workflow 3 (RAGcore Procedure Sync): found and fixed a real defect (three body parameters had a stray trailing `}}`) and a missing Error Workflow wiring, both via the safe `n8n import:workflow` CLI path; exported the corrected, still- inactive workflow as the new source of truth and updated MANIFEST.md/check_drift.py. Publishing it (starts real daily unattended runs) remains a separate decision. RAGcore: root-caused and fixed (live, approved) the "zero retrieval candidates" bug -- a filesystem permission bug (`embedding_profiles.json` unreadable by the app's own runtime user) that broke every retrieval call before it reached Qdrant. Every other suspect (grants, scope resolution, Qdrant filters, embeddings) was verified healthy first. Found a second, deeper gap: the reranker adapter calls an Ollama HTTP route that does not exist on the deployed Ollama version, so `/v1/answers` still returns `not_answerable`. `KNOWLEDGE_PROVIDER` stays `demo` until that is resolved on the RAGcore side. Evidence-based MCP Hub integration status (real tool-call audit history, not just a boolean flag) replaces the old `configured`/`not_configured` guess. Full findings in `docs/final-integrations/current-state-audit.md`. Backend: 172 tests passing, ruff clean, mypy clean (50 files). Frontend: tsc clean, production build clean. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
139 lines
7.5 KiB
Markdown
139 lines
7.5 KiB
Markdown
# 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 views with working search, filters 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, each with a bounded resolution flow, plus 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;
|
||
- two n8n workflows: return processing, and a scheduled data-quality scan with
|
||
crash-recoverable outbox delivery leases;
|
||
- four read-only MCP tools through ITWorx MCP Hub;
|
||
- deterministic demo reset and five-minute showcase.
|
||
|
||
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 demo `KnowledgeProvider` (deterministic TF-IDF extractive retrieval
|
||
over the local procedure documents) is what satisfies the knowledge-assistant
|
||
acceptance criteria and is what's active in production (`KNOWLEDGE_PROVIDER=demo`). A
|
||
`RAGcoreKnowledgeProvider` HTTP adapter is implemented, unit-tested, and has been
|
||
exercised live against the deployed RAGcore instance: a real filesystem-permission bug
|
||
that caused every live retrieval to return zero candidates was found and fixed
|
||
(`docs/final-integrations/current-state-audit.md`), but a second, deeper gap — RAGcore's
|
||
reranker adapter calls an Ollama HTTP route (`/api/rerank`) that does not exist on the
|
||
deployed Ollama version — still blocks real grounded answers. `KNOWLEDGE_PROVIDER` stays
|
||
`demo` until that is resolved on the RAGcore side.
|
||
- **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 health: `http://localhost:8128/health`
|
||
- n8n: `http://localhost:5678`
|
||
|
||
All defaults are configurable via `.env` (see `.env.example`).
|
||
|
||
## Quality gates
|
||
|
||
```bash
|
||
make test # backend: pytest (151 tests)
|
||
make lint # backend: ruff + mypy (strict, zero errors)
|
||
make e2e # frontend: Playwright end-to-end (138 tests, live stack required)
|
||
```
|
||
|
||
Frontend build/typecheck: `cd frontend && npm run build` (`tsc -b && vite build`).
|