MobilityOps/artifacts/evidence/architecture.md

MobilityOps — as-built architecture

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.