MobilityOps/artifacts/evidence/architecture.md

Fleet Ops — as-built architecture

flowchart TB
    UI["Fleet Ops Web\nReact + TypeScript + Vite"]

    subgraph CORE["Fleet Ops — this repository"]
        API["FastAPI /api/v1\nRBAC + domain rules"]
        OUT["Outbox dispatcher\nleases + bounded retry"]
        DB[(PostgreSQL)]
        OBS["Prometheus metrics\nGrafana dashboards"]
        API --> DB
        OUT --> DB
        API --> OBS
    end

    subgraph EXT["Existing external platforms"]
        N8N["Central n8n\nsecondary orchestration"]
        RAG["RAGcore\ngrounded procedure retrieval"]
        HUB["ITWorx MCP Hub\ntool transport + publication"]
    end

    UI -->|secure session cookie| API
    API -->|tenant/workspace adapter| RAG
    OUT -->|vehicle.returned.v1| N8N
    N8N -->|service-authenticated callback| API
    HUB -->|service-authenticated read-only tools| API

Ownership and trust boundaries

Component	Owns	Explicitly does not own
Fleet Ops	vehicles, customers, bookings, inspections, quality issues, audit, permissions, outbox state	external workflow execution or procedure retrieval
RAGcore	indexing/retrieval and grounded procedure evidence	Fleet Ops database or business state
ITWorx MCP Hub	MCP transport, connector publication and central tool-call audit	Fleet Ops database or write actions
n8n	post-commit workflow orchestration	critical business rules or the source-of-truth transaction

End-to-end return trace

sequenceDiagram
    actor Operator
    participant Web
    participant API
    participant DB
    participant n8n
    Operator->>Web: Review and confirm return
    Web->>API: POST return with idempotency key
    API->>DB: Lock booking and validate invariants
    API->>DB: Commit inspection, state, audit and outbox atomically
    API-->>Web: Result + correlation ID
    Web-->>Operator: Human result and full processing trace
    API->>n8n: Deliver persisted outbox event
    n8n->>API: Authenticated status callback
    API->>DB: Persist delivery/audit evidence

Verified reliability properties

1. Concurrent returns serialize through PostgreSQL row locking; only one can commit.
2. Local return success is independent of n8n availability. Pending delivery remains persisted and retryable.
3. Outbox delivery is at-least-once and idempotent by event ID, with crash-recoverable leases and bounded backoff.
4. RAGcore failure affects knowledge answers only. The UI reports unavailable/insufficient evidence and does not invent an answer.
5. MCP endpoints are a separate tenant-bound, client-identity-validated, read-only surface; every call is audited with a correlation ID.
6. Browser authorization is enforced again on the API. Hiding a navigation item is never the security boundary.

The live deployment has exercised all three external boundaries. Local clean-checkout acceptance can use the deterministic extractive knowledge provider while reporting that mode honestly.