Implementation notes / reviewer edition

Technical decisions,
without the hand-waving.

This compact guide explains how the demo preserves evidence across device, database, relay, and destination boundaries.

Run locally

npm --prefix apps/api ci
npm --prefix apps/web ci
npm run dev:api
npm run dev:web

# Web     http://localhost:3000
# API     http://localhost:4100
# OpenAPI apps/api/openapi.yaml

Four independent state dimensions

lifecycle DRAFT → OFFERED → ACCEPTED → PICKED_UP → IN_TRANSIT → RECEIVED → COMPLETEDsync SAVED_ON_DEVICE → WAITING → SYNCING → SYNCED | NEEDS_REVIEWexception NONE → DISCREPANCY_OPEN → RESOLVEDdelivery NOT_STARTED → PENDING → RETRYING → FAILED → DLQ → DELIVERED

Unknown outcome ≠ failed save

If the server applies an offline operation but its response is lost, the client moves to Checking sync result. It queries or retries with the same idempotency key. The API returns the original result, so the mutation is not repeated.

Conflict handling never overwrites the server silently: send the local entry for review, keep it as a separate draft, or use the server version.

Representative API

POST /api/v1/demo/runs
GET /api/v1/demo/runs/:runId
POST /api/v1/sync/operations
GET /api/v1/sync/results/:idempotencyKey
GET /api/v1/shipments
GET /api/v1/shipments/:id
GET /api/v1/shipments/:id/audit/verify
POST /api/v1/exceptions/:id/resolve
POST /api/v1/deliveries/:id/attempt
POST /api/v1/deliveries/:id/replay
GET /api/v1/events

Transactional completion and recovery

Resolving an isolated EX-0037 run appends the resolution, completes the shipment, and inserts the outbox record in one database transaction. The prototype’s API-hosted delivery relay preserves one stable destination key through retries, DLQ movement, and manual replay; a production deployment would split this into a separately scalable worker.

Inspect delivery DL / 019 →

Honest prototype limits

The demo uses synthetic data, illustrative validation rules, and an in-process delivery simulator. AWS queues, authentication, tenancy, and regulatory policy are deliberately outside this portfolio build. OData is an example enterprise adapter only. No claim is made about WiQ’s private architecture, integrations, or regulatory implementation.