Background Sync

Description

Background Sync is responsible for automatically synchronising locally queued data with the server when the device has network connectivity, without requiring the user to manually trigger a sync or keep the app in the foreground. The service monitors connectivity state, processes the sync queue in order, handles retry logic for failed requests, and reports sync status back to the UI. It works in conjunction with the Offline Data Support feature, acting as the delivery mechanism for all queued writes accumulated during offline periods. The sync queue repository maintains a durable, ordered log of pending operations that survives app restarts.

User Flow

Click to expand

Analysis

Business Value

Background Sync ensures that offline-captured data reaches the server reliably and promptly, without placing any burden on the user. If sync were manual, coordinators and peer mentors would need to remember to sync before closing the app - a step that would inevitably be missed, leading to data loss and reporting gaps. Automatic background sync closes this gap entirely, making the offline experience seamless and trustworthy. For organizations depending on accurate Bufdir reporting, knowing that all field-registered activities will be reliably delivered to the backend without manual intervention is a strong trust signal and a prerequisite for organizational adoption.

Implementation Notes

The background sync service uses Flutter's WorkManager plugin (via flutter_workmanager) for scheduling periodic background tasks on both Android and iOS, respecting platform-imposed background execution limits. The sync queue repository stores pending operations in the local SQLite database with metadata including timestamp, operation type, entity ID, payload, retry count, and last error. The service processes the queue sequentially, sending REST API requests and marking items as completed on HTTP 2xx responses. Exponential backoff with jitter is applied on failure, and items exceeding a configurable retry threshold are flagged for user review. Connectivity state is monitored using the connectivity_plus package to trigger immediate sync when transitioning from offline to online.