Initial MobilityOps build pack (docs, contracts, scaffold)

docs/03-architecture.md

@@ -0,0 +1,55 @@
+# Architecture
+
+## Context
+
+```text
+External AI client
+      |
+      v
+ITWorx MCP Hub ---------> RAGcore
+      |                      ^
+      v                      |
+MobilityOps API <------ MobilityOps UI
+      |
+      +---- PostgreSQL
+      |
+      +---- Outbox dispatcher ----> n8n
+```
+
+## Ownership
+
+### MobilityOps
+
+Owns vehicles, customers, bookings, inspections, maintenance summaries, data-quality issues, audit events and integration delivery state.
+
+### RAGcore
+
+Owns procedure ingestion, chunking, embeddings, retrieval and grounded answer generation. MobilityOps stores only document references and last-known synchronization state where useful.
+
+### ITWorx MCP Hub
+
+Owns MCP transport, tool publication, client policy and central tool audit. The hub calls versioned MobilityOps APIs and RAGcore APIs. It never reads the MobilityOps database.
+
+### n8n
+
+Receives committed events and orchestrates secondary work. It does not decide whether a vehicle return is valid or what the canonical vehicle status is.
+
+## Reliability boundaries
+
+1. A return command and its outbox event commit in one database transaction.
+2. Outbox delivery is at-least-once; the n8n workflow and callback endpoint are idempotent by event ID.
+3. RAGcore failure disables knowledge answers only.
+4. MCP Hub failure does not affect the MobilityOps web application.
+5. n8n failure leaves events pending with bounded retries and visible status.
+
+## Security boundaries
+
+- browser uses application authentication;
+- service-to-service calls use scoped tokens;
+- no arbitrary SQL, shell or generic HTTP tools;
+- read-only MCP tools only for the PoC;
+- user and service actions are distinguishable in audit events.
+
+## Deployment
+
+MobilityOps may run in its own Compose project. RAGcore and MCP Hub are configured by URL and credentials and may be on another internal Docker network or behind TLS endpoints.