NuklearRabbit
6f77a30dce
The demo seed plants exactly one failed delivery (BK-H-0020) to demonstrate retry and audit. Because derive_n8n_status() counted any failure, every fresh reset pinned the n8n integration to "degraded" -- the demo showed a warning about a prop, which tells a viewer something untrue about the automation. The seeded failure now carries its own error code, demoScenarioTimeout, rather than the generic connectionError a real timeout produces. No column and no migration: last_error_code already existed, is already surfaced to the UI and is already localizable. - integration status splits failed into unexpected_failed and demo_scenario_failed; only unexpected failures may move the state. A staged failure alone leaves n8n operational. - latest_failure_at is a health signal and now ignores the staged failure; latest_demo_scenario_at reports it separately. - /api/v1/workflows exposes is_demo_scenario. The Automation page labels the run as a prepared demo scenario, explains that it is a simulated temporary failure that does not affect automation health, and offers a distinct "retry demo scenario" action. Translated in nl-BE, en-GB and fr-BE. - the carve-out stays narrow: a real failure still degrades n8n, and a genuine later failure of the same event overwrites the demo code with the real one. - the retry itself is unchanged and real: the event goes back on the outbox and the dispatcher delivers it to n8n like any other, so 19+1 becomes 20+0 only on an actual round trip. The audit records which kind of failure was retried. Tests that assert on the seeded scenario now reseed first, since earlier test files legitimately mutate the outbox and the suite shares one database. Verified locally against a real PostgreSQL 16: 181 passed, ruff clean, mypy clean (50 files), tsc clean, frontend build clean. Not deployed and not browser-verified.
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
pendingwith 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/statusreports 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). ARAGcoreKnowledgeProviderHTTP 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_PROVIDERstaysdemountil 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_ENABLEDis actually wired intoSettingsand 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 tovehicleRef).
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
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
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).