# 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.

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.

## 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`).
- `artifacts/design-validation/` — baseline audit, Stitch direction references and implemented responsive captures.

## 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 (18 tests, live stack required)
```

Frontend build/typecheck: `cd frontend && npm run build` (`tsc -b && vite build`).