Initial MobilityOps build pack (docs, contracts, scaffold)

2026-08-01 20:34:43 +02:00
commit 24188d9b10
71 changed files with 3412 additions and 0 deletions
@@ -0,0 +1,41 @@
+# n8n integration
+
+## Role
+
+n8n orchestrates secondary cross-system work after MobilityOps commits canonical state. It is not the domain engine.
+
+## Required live workflow: return processing
+
+Input: `vehicle.returned.v1` webhook event.
+
+Steps:
+
+1. validate event type and schema;
+2. derive a follow-up category from the already-calculated state;
+3. call the narrow MobilityOps callback endpoint with event ID and follow-up summary;
+4. return a stable workflow result;
+5. on errors, fail visibly so the outbox dispatcher can retry.
+
+The starter export is `n8n/mobilityops-return-processing.json`. Claude may correct its credentials and callback route but must preserve idempotency.
+
+## Optional second workflow: knowledge sync
+
+Input: manual trigger or manifest-changed event.
+
+Steps:
+
+1. read the fixed knowledge manifest;
+2. call RAGcore ingestion/sync API;
+3. record per-document results through MobilityOps integration status API.
+
+This workflow is useful but must not delay the core demo if RAGcore's final API is not ready.
+
+## Outbox dispatcher
+
+- polls pending records;
+- claims with `FOR UPDATE SKIP LOCKED` or equivalent;
+- sends event with timeout;
+- exponential backoff with a small maximum attempt count;
+- supports explicit manual retry;
+- preserves last error and response metadata;
+- does not hold a database transaction open during network I/O.