# MobilityOps — as-built architecture

```mermaid
flowchart TB
    subgraph Browser
        UI["MobilityOps Web<br/>React + TypeScript"]
    end

    subgraph MobilityOps["MobilityOps (this repo)"]
        API["FastAPI backend<br/>/api/v1/*"]
        DISPATCH["Outbox dispatcher<br/>background thread"]
        DB[(PostgreSQL)]
        API --> DB
        DISPATCH --> DB
    end

    subgraph External["External central services"]
        N8N["n8n<br/>return-processing workflow"]
        RAGDEMO["Demo KnowledgeProvider<br/>TF-IDF extractive, local files"]
        RAGCORE["RAGcore<br/>(adapter built, no live instance)"]
        HUB["ITWorx MCP Hub<br/>(endpoints built, no live instance)"]
    end

    UI -->|session cookie| API
    API -->|GroundedAnswer| RAGDEMO
    API -.->|configurable, unavailable-safe| RAGCORE
    DISPATCH -->|POST vehicle.returned.v1| N8N
    N8N -->|callback, X-Service-Token| API
    HUB -.->|X-Service-Token, read-only| API

    classDef unverified stroke-dasharray: 5 5;
    class RAGCORE,HUB unverified;
```

Dashed boxes/arrows are implemented and unit/contract-tested but were never exercised
against a live instance in this environment (no reachable RAGcore or ITWorx MCP Hub).
Solid boxes were verified end-to-end, including a real n8n instance.

## Component responsibility (unchanged from `docs/03-architecture.md`)

| Component | Owns |
|---|---|
| MobilityOps | vehicles, customers, bookings, inspections, data-quality issues, audit, outbox/delivery state |
| RAGcore | procedure retrieval and grounded answers (demo provider substitutes locally) |
| ITWorx MCP Hub | MCP transport, tool publication, central tool-call audit |
| n8n | post-commit secondary orchestration only — never the source of truth for vehicle state |

## Reliability boundaries verified in this build

1. **Return commits atomically with its outbox event** — `app/services/returns.py`, one
   transaction; verified by `test_concurrent_returns_only_one_succeeds` (real Postgres row
   locking, not mocked).
2. **Outbox delivery is at-least-once, idempotent by event ID** — verified live: the n8n
   callback checks for an existing `AuditEvent` by event ID before recording a second time.
3. **RAGcore failure disables knowledge answers only** — `RAGcoreKnowledgeProvider` degrades
   to `unavailable`; the rest of the app is unaffected because the knowledge router is the
   only consumer.
4. **MCP Hub failure does not affect the web application** — the four MCP provider
   endpoints are a separate authenticated surface (`X-Service-Token`), invisible to the
   browser-facing API/UI.
5. **n8n failure leaves events pending with bounded retries** — verified live: a seeded
   `failed` event, retried through the UI, was picked up by the background dispatcher and
   delivered through the real n8n instance within one poll cycle.