69 lines
2.9 KiB
Markdown
69 lines
2.9 KiB
Markdown
# 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.
|