Design the bidirectional sync protocol #23

Open
opened 2026-10-30 21:01:04 -06:00 by west · 0 comments
Owner

📋 Design how sync works between iOS client and server.

🎯 Acceptance Criteria:

  • Protocol documented with request/response JSON schemas
  • Client sends: { cursor: N, outbox_actions: [...] } to server
  • Server replays client actions, assigns server sequence numbers
  • Server responds: { cursor: M, outbox_actions: [...] } for client to replay
  • Cursor semantics defined (monotonic counter, per-device or global)
  • Conflict resolution strategy: last-write-wins by entity last_modified timestamp
  • Deleted entity handling: tombstone markers or soft delete in payload
  • Sync trigger: automatic on network change + manual trigger
  • Payload format finalized (JSON structure for actions)

📝 Notes: This is the most complex design document. The outbox pattern means no mutation is ever lost. Consider: should the cursor be per-device or global? Per-device allows more parallelism but is more complex.

📋 **Design how sync works between iOS client and server.** 🎯 **Acceptance Criteria:** - [ ] Protocol documented with request/response JSON schemas - [ ] Client sends: { cursor: N, outbox_actions: [...] } to server - [ ] Server replays client actions, assigns server sequence numbers - [ ] Server responds: { cursor: M, outbox_actions: [...] } for client to replay - [ ] Cursor semantics defined (monotonic counter, per-device or global) - [ ] Conflict resolution strategy: last-write-wins by entity last_modified timestamp - [ ] Deleted entity handling: tombstone markers or soft delete in payload - [ ] Sync trigger: automatic on network change + manual trigger - [ ] Payload format finalized (JSON structure for actions) 📝 **Notes:** This is the most complex design document. The outbox pattern means no mutation is ever lost. Consider: should the cursor be per-device or global? Per-device allows more parallelism but is more complex.
Sign in to join this conversation.
No description provided.