ADR-0002: Sync Transport, Ordering, and Idempotency

• Status: Accepted
• Date: 2026-04-10

Context — ADR-0003

The app must sync queued offline events safely, preserve history, and avoid duplicate side effects during retries. Conflicts must apply admin precedence and keep loser events auditable.

Decision — ADR-0003

Use HTTPS JSON batch transport for event sync via a versioned endpoint.

Protocol rules:

• client submits ordered event batches with device identifier and timestamps
• protected sync requests require auth and idempotency key
• server returns synced, failed, and conflicts arrays
• retries with same idempotency key and payload must be replay-safe
• conflict payload must include applied policy and winner or loser event identifiers

Ordering rules:

• preserve client submission order within a batch
• server assigns authoritative server timestamps
• no event deletion on conflict, only supersession markers

Consequences — ADR-0003

Benefits:

• deterministic retry behavior
• explicit conflict visibility for UI and audit flows
• contract aligns with backend-primary queue model (offline fallback queues sync)

Tradeoffs:

• requires strict server-side idempotency enforcement
• requires correlation and observability instrumentation

Alternatives Considered — ADR-0003

• websocket-first sync: deferred to future due to higher operational complexity
• per-event mutation endpoints only: rejected for retry overhead and weaker ordering control
• last-write-wins without role precedence: rejected due to business rule violation

References — ADR-0003

• ../../product/prd.md
• ../srs.md
• ../sdd.md
• ../../reference/api/api-contract.md
• ../../reference/data-dictionary.md
• Requirement IDs: FR-015, NFR-006, NFR-012, SR-001, SR-002, SR-003, SR-004, SR-005