NuklearRabbit
4bf9afbeff
Ran a dedicated post-M7 release-readiness audit. Found and fixed the one real gap: mypy was a declared dev dependency but had never been run in any milestone's validation loop. Fixed all 43 pre-existing type errors it surfaced, including two genuine defensive- programming gaps (unguarded Optional vehicle/customer lookups that could have crashed with unhandled 500s instead of clean 404/401 responses) rather than suppressing them. make lint now runs ruff + mypy; mypy reports zero errors across 44 source files. Re-verified end to end against a genuinely wiped-volumes clean checkout: automatic migrations, deterministic seed, 66/66 backend tests, and the full user-journey matrix (login, dashboard, vehicle/booking detail, return workflow, invalid-mileage rejection, data-quality review, duplicate-customer merge, audit trail, Knowledge Assistant, n8n, MCP Hub) via curl and Playwright. Live-verified both external-dependency degraded modes, not just unit tests: stopped n8n mid-flow and confirmed a return still commits with the outbox event staying pending and retrying with backoff, then self-healing to succeeded with zero manual intervention once n8n came back; verified RAGcore's unavailable-degradation path against an unreachable host. Added frontend/e2e/interactive-elements.spec.ts (11 tests covering every nav item, filter, tab, and role boundary) alongside the existing demo script test — 12/12 e2e tests passing. Verified no secrets are committed (.env never tracked, clean git history scan) and .env.example covers every operator-configurable setting. Confirmed no placeholders, TODOs, fake responses, hardcoded metrics, or dead routes anywhere in the codebase. Updated README.md with an honest integration-status section and PROJECT_STATE.md with the full audit findings. Added artifacts/final-acceptance/summary.md as the authoritative final evidence document (commands, results, URLs, demo access, integration status per external dependency, known limitations, deployment instructions, five-minute demo flow).
85 lines
3.6 KiB
Markdown
85 lines
3.6 KiB
Markdown
# MobilityOps
|
|
|
|
**Connected operations for vehicle rental and service teams.**
|
|
|
|
MobilityOps 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.
|
|
|
|
All people, companies, vehicles, bookings and documents are synthetic. The workflows, validation, integrations, audit logging and access boundaries are intended to be real.
|
|
|
|
## Scope
|
|
|
|
The PoC implements:
|
|
|
|
- operations dashboard;
|
|
- vehicle and booking views;
|
|
- one complete vehicle-return workflow;
|
|
- five deterministic data-quality checks;
|
|
- human review and customer merge;
|
|
- audit trail;
|
|
- RAGcore-backed knowledge assistant with citations;
|
|
- one n8n return-processing workflow;
|
|
- 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) and the failed-delivery manual-retry path.
|
|
- **RAGcore**: the demo `KnowledgeProvider` (deterministic TF-IDF extractive retrieval
|
|
over the local procedure documents) is what satisfies the knowledge-assistant
|
|
acceptance criteria and is fully verified. A `RAGcoreKnowledgeProvider` HTTP adapter is
|
|
implemented and unit-tested, including its unavailable-degradation path, but was never
|
|
exercised against a live RAGcore instance in this environment.
|
|
- **ITWorx MCP Hub**: the four read-only provider endpoints are implemented, tested, and
|
|
directly `curl`-verified with correct auth enforcement and audit logging. No live Hub
|
|
instance was reachable in this environment to verify an actual Hub round trip.
|
|
|
|
See `artifacts/final-acceptance/summary.md` for full verification evidence and exact
|
|
commands.
|
|
|
|
## 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`).
|
|
|
|
## 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 (66 tests)
|
|
make lint # backend: ruff + mypy (strict, zero errors)
|
|
make e2e # frontend: Playwright end-to-end (12 tests, live stack required)
|
|
```
|
|
|
|
Frontend build/typecheck: `cd frontend && npm run build` (`tsc -b && vite build`).
|