A courier's scans reach the system

sequence

From a barcode scan on an offline handheld to the recipient's SMS

Step 1: scan the barcode1. scan the barcodeStep 2: POST /v1/scans · the whole batch, over mTLS2. POST /v1/scansthe whole batch, over mTLSStep 3: insert if new · unique index on idempotency_key3. insert if newunique index on idempotency_keyStep 4: inserted?4. inserted?Step 5: parcel.scanned5. parcel.scannedStep 6: count it as a duplicate6. count it as a duplicateStep 7: 200 OK · accepted, duplicates7. 200 OKaccepted, duplicatesStep 8: parcel.scanned8. parcel.scannedStep 9: apply the scan · ordered by scanned_at, not arrival9. apply the scanordered by scanned_at, not arrivalStep 10: UPDATE parcel status10. UPDATE parcel statusStep 11: ok11. okStep 12: parcel.delivered12. parcel.deliveredStep 13: parcel.delivered13. parcel.deliveredStep 14: send the delivered SMS14. send the delivered SMSStep 15: queued15. queuedalt[a scan we have not seen][already held: the batch was replayed]loop[for each scan in the batch]opt[it was a delivery scan]Offline for hours is normal. Scansqueue on the device, each with anidempotency key.CourierCourierCourier handheld · Kotlin / AndroidCourier handheldKotlin / AndroidScan ingest · Go · The only service that knows about devicesScan ingestGoRelay DB · PostgreSQL 15Relay DBPostgreSQL 15Parcel events · KafkaParcel eventsKafkaDispatch · Java / SpringDispatchJava / SpringNotifier · Node.jsNotifierNode.jsTwilioTwilioexternal
drag a box to move it · drag empty space to pan · wheel to zoom · click a node

Why the loop matters

  • The same batch may arrive twice if an upload times out. The unique index makes replaying it change nothing.
  • Late scans are published like fresh ones; Dispatch orders by scanned_at.