Kordant/tasks/android-production/23-offline-sync.md

23. Offline Sync & Conflict Resolution

meta: id: android-production-23 feature: android-production priority: P2 depends_on: [android-production-21] tags: [backend, offline, production]

objective:

• Implement robust offline mode with sync conflict resolution for all user actions

deliverables:

• Offline queue improvements
• Sync conflict resolution strategy
• Offline UI indicators
• Data consistency guarantees

steps:

1. Audit existing offline support:
   • Review android/app/.../data/sync/SyncManager.kt
   • Review OfflineWorker.kt
   • Review PendingRequestQueue.kt
   • Identify gaps in offline handling
2. Improve offline queue:
   • Support all mutation types (add, update, delete)
   • Add request deduplication
   • Add request ordering (dependencies)
   • Increase max retry count with exponential backoff
3. Implement conflict resolution:
   • Define strategy per data type:
     • Server wins for most data (alerts, exposures)
     • Last write wins for user preferences
     • Merge for watchlist items
   • Add conflict detection (version numbers or timestamps)
   • Show conflict UI for manual resolution (if needed)
4. Add offline UI:
   • Offline indicator in status bar
   • Disabled actions when offline
   • "Sync pending" badges on modified items
   • Pull-to-refresh with offline state
5. Implement data consistency:
   • Optimistic updates (update UI immediately, sync in background)
   • Rollback on sync failure
   • Verify server state after sync
   • Handle partial sync failures
6. Add background sync:
   • Process queue on app foreground
   • Process queue on network restoration
   • Schedule periodic sync attempts
7. Test offline scenarios:
   • Create watchlist item offline → syncs when online
   • Delete exposure offline → syncs when online
   • Modify settings offline → syncs when online
   • Conflicting edits on multiple devices

tests:

• Unit: Test queue ordering and deduplication
• Integration: Test sync after offline period
• E2E: Test conflicting edits resolution

acceptance_criteria:

• All mutations queued when offline
• Queue processed automatically when online
• Optimistic updates show immediately
• Failed operations roll back UI changes
• Conflict resolution strategy defined per data type
• Offline indicator visible in UI
• Sync pending badges on modified items
• No data loss during sync failures
• Background sync on app foreground and network restore
• Unit tests for all offline scenarios

validation:

• Enable airplane mode → create watchlist item → badge shows
• Disable airplane mode → item syncs → badge clears
• Edit same item on web and Android → conflict resolved correctly
• Kill app during sync → queue persists, resumes on relaunch

notes:

• SyncManager.kt and OfflineWorker.kt already exist but may need enhancement
• Room database can help with offline queue persistence
• Simple server-wins strategy is acceptable for MVP
• Consider using WorkManager for reliable background sync