# Fleet Ops — as-built architecture

```mermaid
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

```mermaid
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.