Attach Documents Offline and Sync When Connectivity Is Restored
Peer mentors frequently operate in community centers, private homes, or outdoor venues where connectivity is unreliable. If a document attachment is initiated offline, the file should be stored locally (compressed if needed) and queued for upload. The UI should show a 'Pending upload' state for queued attachments. When the device reconnects, queued uploads are processed automatically in the background. The peer mentor is notified via an in-app notification or live region announcement when queued attachments have been successfully synchronized. The local storage adapter and activity attachment repository must handle this queue persistently across app restarts.
User Story
Acceptance Criteria
- Given I am offline and attach a document to an activity, when I confirm the selection, then the file is stored locally and shown in the thumbnail grid with a 'Pending upload' indicator
- Given there is a pending attachment queue, when the device regains internet connectivity, then all queued files are uploaded automatically in the background
- Given background sync completes successfully, when all queued attachments are uploaded, then the 'Pending upload' indicators are replaced with normal thumbnails and a success notification is shown
- Given the app is closed and reopened while offline, when the app launches, then any previously queued attachments are still present in the pending queue
- Given a queued attachment fails to upload after reconnecting (e.g., server error), when the failure occurs, then the thumbnail remains in a 'Failed' state with a manual retry option
- Given the offline attachment queue contains a file, when navigated with a screen reader, then the 'Pending upload' state is announced for each queued thumbnail
Business Value
Peer mentors visit participants in hospitals, rural communities, and private residences where internet access cannot be guaranteed. Requiring connectivity for attachment upload creates a hard blocker that either prevents activity registration entirely or forces peer mentors to return to the activity later — a significant friction point that drives underreporting. Offline queuing ensures 100% of activities can be documented at the time they occur, regardless of connectivity, which directly improves reporting completeness for Bufdir and organizational statistics.
Components
- Attachment Picker UI ui
- Attachment Thumbnail Grid ui
- Attachment Upload Service service
- Activity Attachment Repository data
- Supabase Storage Adapter infrastructure
- Receipt Image Compressor service
- Live Region Announcer ui
- Plain Language Error Display ui