Background Sync

The mutation outbox created by offline-first persistence is only valuable if mutations reliably reach the server. Background Sync closes that loop: it transforms the local store from a private cache into a durable, eventually consistent replica of the server state. Without it, peer mentors would need to manually trigger uploads, reintroducing the friction the offline layer was designed to eliminate - and creating a serious risk that activity records are never submitted to the server and therefore never included in Bufdir reports. Exponential backoff with jitter is important for multi-organization deployments: if many devices simultaneously regain connectivity (e.g., after a conference or training event), naive retry logic would generate a thundering herd that degrades API performance for all users. The backoff strategy protects server stability and ensures fair resource sharing across organizations. Dead-letter handling with user notification ensures no mutation is silently lost, which is critical for organizations whose Bufdir funding depends on complete and accurate activity records.

Flutter's connectivity_plus package is used to detect network state changes; a stream subscription in the sync queue service triggers an immediate drain attempt when the device transitions from offline to online. Background execution is implemented via WorkManager (Android) and BGTaskScheduler (iOS) through the workmanager Flutter plugin, scheduling a periodic sync task with a minimum interval of 15 minutes when the app is backgrounded. The sync loop reads the outbox in FIFO order, dispatches each mutation via ApiHttpClient, and commits the result (success or failure) back to the outbox within a Drift transaction to guarantee atomicity. The retry backoff service implements truncated exponential backoff: delay = min(base * 2^attempt + jitter, max_delay), with base=30s, max_delay=3600s, and jitter drawn from a uniform random range of ±20% of the computed delay. After a configurable threshold (default: 10 retries), the item is marked dead-letter and a local notification is dispatched via the push notification service to alert the user. Sync state (pending count, last sync timestamp, dead-letter count) is exposed as a Riverpod AsyncNotifier and consumed by the home screen status bar widget and the settings screen sync diagnostics panel.