Skip to main content

Orders Service — Sync Contract

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template

1. Sync Philosophy​

The orders-service is server-authoritative. Orders are clinical instructions requiring CDS validation at the time of entry; offline-created orders must be queued and validated against live CDS rules on submission. No offline-first write pattern is permitted for medication orders due to patient safety requirements. Non-medication orders (lab, radiology requisitions) may be queued offline with re-validation on sync.

2. Conflict Policies by Aggregate​

AggregateConflict policyResolution rule
Order (medication)Server-authoritative; no offline createMobile app must buffer and submit only when connected; CDS runs on server at submission time
Order (lab/radiology)Server-authoritative with offline queueclientMutationId deduplication; submitted on reconnect; CDS runs on server
Order (referral)Server-authoritativeReferral cannot be created offline
OrderSetServer-authoritativeOrder set templates are read-only on mobile; created only via connected session

3. Offline Scenarios​

ScenarioBehaviour
Clinician creates medication order offlineApp rejects offline creation; shows connectivity required message
Clinician creates lab requisition offlineOrder stored in device queue with clientMutationId; submitted on reconnect; CDS validation runs at submission
Patient allergy added while order is being created offlineCDS on server at activation time catches allergy; app must fetch updated CDS alerts before activation
Order cancelled offlineCancellation queued; submitted on reconnect; if order already completed, server returns ORDER_TERMINAL_STATE

4. Version Field Usage​

  • All Order mutations require the current version in the request body.
  • Server increments version on each state transition.
  • Mismatch returns 409 OPTIMISTIC_LOCK_CONFLICT.
  • Client must re-fetch, re-apply intent, and resubmit.

5. Idempotency​

  • POST /v1/orders accepts clientMutationId in request body.
  • Server caches processed clientMutationId in Redis for 24 hours.
  • Duplicate submission within 24 hours returns the original 201 response.
  • POST /v1/orders/batch accepts per-item clientMutationId.

6. CDS at Sync Time​

When a queued non-medication order is submitted after offline period:

  • CDS allergy and duplicate checks run against current server state.
  • If a new allergy was added while offline, the CDS check may produce alerts not present at queue time.
  • Client must re-present CDS alerts to clinician before activation.