Background Sync
Feature Detail
Description
Background Sync is the engine that drains the mutation outbox and reconciles local state with the server whenever network connectivity is available, running as a background worker so the user does not need to keep the app in the foreground to complete synchronisation. The worker processes queued mutations in order, handles transient network failures with retry and backoff, maps temporary offline IDs to server-assigned IDs, and triggers state refresh in Riverpod notifiers once a batch is confirmed. It integrates with platform background-execution APIs (WorkManager on Android, BGTaskScheduler on iOS) to ensure sync completes even when the app is suspended.
Sources & reasoning
Lines 300-303 explicitly name the sync queue with retry/backoff and ID mapping as architectural components, which map directly to the BackgroundSyncWorker and SyncQueueService in the blueprint. Lines 50-54 reinforce that parallel operation during rollout requires the app's data to stay consistently synchronised with existing systems - silent background sync is the mechanism that makes this possible. The blueprint assigns MVP, consistent with offline-first being a launch-day architectural commitm
-
docs/source/likeperson.md · line 300-303Offline-first persistence (Drift + SQLCipher encrypted local DB, mutation outbox, sync queue with retry/backoff, ID mapping for offline-created entities, conflict resolver)
-
docs/source/likeperson.md · line 50-54Sterk enighet på tvers: Eksisterende løsninger må fungere parallelt til appen er godt etablert. Ingen av organisasjonene tåler et hard-cut.
Analysis
Without a reliable background sync mechanism, mutations queued offline would only be delivered when the user actively opens the app and waits, creating an unpredictable window during which Bufdir-reportable activities are absent from the server. HLF's example of a peer mentor with 380 registrations per year illustrates the volume; any sync unreliability compounds into significant data loss at scale. Coordinators who rely on near-real-time visibility of peer mentor activity for oversight and approval workflows also depend on sync completing promptly. Background sync transforms the offline capability from a local notepad into a trustworthy distributed system, which is the basis on which all four organisations can adopt the platform as their primary reporting tool.
On Android the background worker uses WorkManager with a network-type constraint set to CONNECTED, scheduling periodic sync every 15 minutes and an immediate one-off sync on connectivity change via ConnectivityManager broadcast. On iOS BGAppRefreshTask and BGProcessingTask are registered; the app requests background time on connectivity restoration via NWPathMonitor. The sync worker reads the mutation outbox table in FIFO order, replays each operation against the REST API with JWT bearer auth (auto-refreshing via the ApiHttpClient 401 handler), and on success marks the row as synced and updates the ID-mapping table. Partial batch failures leave unsynced rows intact for the next run. A SyncQueueService Riverpod provider exposes sync status (idle, syncing, error) to the UI layer. The BackgroundSyncWorker runs in a Dart isolate to avoid blocking the UI thread.
Components (7)
Shared Components
These components are reused across multiple features
User Stories
No user stories have been generated for this feature yet.