Background Sync
Feature Detail
Description
Background Sync manages the upload and reconciliation cycle that moves queued local mutations to the backend when connectivity is available. A sync queue with retry and exponential backoff processes the mutation outbox, while a conflict resolver handles cases where the same entity was modified both locally and remotely. The service operates transparently in the background, keeping the app consistent without interrupting the user's workflow.
Sources & reasoning
The architecture section names a sync queue with retry/backoff and a conflict resolver as distinct components from the offline store - justifying Background Sync as a separate feature from Offline Data Support. The blueprint marks it MVP. Reliable background sync is prerequisite for the mutation outbox model to function safely; without it, offline-captured data remains stranded on device indefinitely.
No source references — this artifact was included based on reasoning alone (see above).
Analysis
Without a reliable sync layer, offline-captured data would require manual user action to upload, creating friction and risk of missed submissions. Background Sync ensures that activity registrations, expense entries, and contact edits flow to the server automatically and verifiably, preserving Bufdir reporting integrity. The conflict resolver prevents silent data corruption when coordinators and peer mentors edit the same record independently - critical for proxy reporting scenarios where both parties may update an activity simultaneously.
The sync queue is an ordered table in the Drift database; each row holds operation type, target entity, serialized payload, attempt count, and last-attempt timestamp. A Flutter background isolate or WorkManager task polls the queue on connectivity events and scheduled intervals, using exponential backoff (1s, 2s, 4s … 60s cap) for transient failures. The conflict resolver applies last-write-wins by default using server-side timestamps, with hooks for future per-entity strategies. JWT auto-refresh in ApiHttpClient handles token renewal during long offline periods before sync attempts begin.
Components (47)
Shared Components
These components are reused across multiple features
Service Layer (11)
Data Layer (23)
Infrastructure (7)
User Stories
No user stories have been generated for this feature yet.