NuklearRabbit
108b5d04fc
Automated migrations on container startup (backend/entrypoint.sh), scripted n8n workflow activation (make n8n-setup), Playwright E2E test covering the full 9-step demo script (verified passing against the live stack, including the previously-unverified 360px responsive layout), evidence screenshots of all main pages, architecture diagram, and artifacts/evidence/final-summary.md with commit/commands/test counts/RAGcore and n8n evidence/MCP sample calls/known limitations/portfolio wording. Verified the complete clean-checkout path from a genuinely wiped-volumes state: automatic migrations, seed, 66 backend tests passing, and a live S1 return round-tripped through a freshly-activated n8n instance. Added .gitattributes to force LF line endings on shell scripts, preventing a real cross-platform breakage of entrypoint.sh's shebang.
64 lines
2.8 KiB
Markdown
64 lines
2.8 KiB
Markdown
# 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.
|