Attach Receipt When Offline and Sync When Connected
Peer mentors often register expenses immediately after visits in locations with poor connectivity. The app must allow offline capture and form completion, caching the receipt image locally. When connectivity is restored, the pending upload is processed automatically in the background and the claim is submitted. The user is notified of successful background submission via an in-app notification. If the background sync fails, the claim remains in a 'pending upload' state visible in the expense list with a retry option. This is particularly important for rural or hospital-visit scenarios where connectivity is unreliable.
User Story
Audience Summaries
Offline receipt capture directly addresses the underreporting problem identified as critical by all three partner organizations. Peer mentors frequently operate in rural areas, hospitals, and low-connectivity environments — forcing online-only submission creates friction that results in lost or delayed claims, undermining both program integrity and mentor trust. By enabling offline form completion with automatic background sync, the platform removes a fundamental barrier to adoption. This capability is not a convenience feature but a core requirement for the product to function in its intended deployment context.
Successful offline support directly correlates with higher claim submission rates, more accurate program cost tracking for Bufdir reporting, and stronger mentor retention. Organizations that cannot rely on expense reimbursement workflows will seek alternative tools, making this a competitive differentiator.
This story carries medium priority but high implementation complexity due to its cross-cutting nature — it touches the mobile UI layer, local storage strategy, background job processing, network state detection, and notification delivery. Effort estimation should account for native-side offline queue management, conflict resolution logic if duplicate submissions occur, and thorough testing across varied network degradation scenarios. Key dependencies include the receipt capture story (story-receipt-capture-and-attachment-peer-mentor-004) and a stable background sync infrastructure. UAT must simulate real-world connectivity patterns: airplane mode, intermittent signal, and mid-upload drops.
Rollout risk is moderate — a poorly implemented retry mechanism could result in duplicate claim submissions, requiring defensive idempotency checks on the backend. Coordinate with QA early to define connectivity test matrix and with UX to validate 'Waiting for connection' and retry states against accessibility standards.
Implementation requires a local persistence layer (e.g., SQLite or AsyncStorage) to cache claim form data and receipt image blobs when the device is offline. On form submission, check network availability; if offline, write to the local queue with a 'pending_upload' status flag. A background task (React Native BackgroundFetch or equivalent) must monitor network state and process the queue when connectivity is restored. The upload sequence must follow atomic semantics: upload the receipt image to Supabase Storage first, obtain the storage path, then submit the claim record — never submit without a confirmed storage URL.
Implement idempotency keys on the claim insert to prevent duplicates on retry. On success, clear the local image cache and fire an in-app notification via the notification service. Expose retry affordance and human-readable failure reasons in the expense list UI. Edge cases: partial upload failure, storage quota exceeded, app killed mid-sync, and simultaneous connectivity restoration across multiple pending claims.
Acceptance Criteria
- Given I have no internet connection, When I capture a receipt and fill in the expense form, Then I can complete the form and the claim is saved locally in a pending state
- Given a claim is in pending state due to no connectivity, When I view the expense list, Then the pending claim is shown with a 'Waiting for connection' indicator
- Given connectivity is restored, When the app detects the network, Then pending uploads are processed automatically in the background without requiring me to reopen the form
- Given the background upload and submission succeed, When the operation completes, Then I receive an in-app notification confirming the claim was submitted
- Given the background sync fails after connectivity returns, When I view the pending claim, Then a Retry button is available and the failure reason is shown in plain language
- Given an image is cached locally for offline use, When it is successfully uploaded, Then the local cache is cleared to free device storage
Business Value
Offline capability is essential for the core use case: peer mentors visiting contacts at home, in hospitals, or in rural areas where connectivity is unreliable. Forcing online-only expense registration introduces friction that leads to the underreporting problem all three organizations identified as critical. Background sync ensures no claims are lost while maintaining data integrity through atomic upload-before-submit semantics.
Components
- Receipt Camera Sheet ui
- Receipt Attachment Service service
- Receipt Image Compressor service
- Receipt Storage Repository data
- Claim Receipt Repository data
- Expense Form BLoC service
- Expense Submission Service service
- Supabase Storage Adapter infrastructure
- Notification List Item Widget ui
- Plain Language Error Display ui