Offline Search Against Locally Cached Contacts
Coordinators and peer mentors often operate in environments with unreliable connectivity — home visits, rural areas, or public transport. The offline search capability maintains a synchronized local cache of contacts (excluding encrypted sensitive fields) on the device, served by the offline search repository. When the device is offline, the search screen transparently falls back to local cache queries, returning results with appropriate indicators. Cache synchronization runs in the background when connectivity is restored, ensuring the local copy stays current. The cache excludes fields governed by field-level encryption (such as Blindeforbundet's epikrise data) and respects all data minimization principles.
User Story
Audience Summaries
Field coordinators and peer mentors for organizations like Blindeforbundet, NHF, and HLF routinely operate in low-connectivity environments — rural chapter visits, home care settings, and public transport. This story removes a critical blocker to service delivery by ensuring contact lookup never depends on internet availability. The business impact is direct: coordinators can continue coordinating without interruption, reducing missed follow-ups and improving the reliability of the peer mentoring service as a whole. For organizations serving visually impaired and hearing-impaired members in geographically dispersed regions, this capability is not a convenience but a baseline operational requirement.
Retention of coordinators and peer mentors is strengthened when tooling works in the field rather than only in offices. This also demonstrates organizational commitment to accessibility-first design, reinforcing trust with member organizations and their stakeholders. Data minimization compliance — excluding encrypted sensitive fields from the local cache — ensures the feature meets privacy obligations without compromising utility.
This story has high delivery complexity due to the multi-layer data synchronization requirement and the need to coordinate between the offline search repository, the background sync service, and the existing online Supabase query path. Effort estimation should account for cache schema design, conflict resolution logic when syncing after reconnection, and the UI indicator for offline mode. Acceptance criteria require measurable performance targets (sub-500ms offline query response) that will need device-level performance testing across representative hardware. Dependencies exist on the contact search story (story-contact-and-notes-search-coordinator-001), so sequencing must be validated before sprint planning.
Stakeholder involvement should include privacy and compliance reviewers to confirm that field-level encryption exclusions align with Blindeforbundet's data handling agreements. Rollout risk centers on first-time sync behavior — the empty-state flow for users who have never synced must be user-tested to avoid confusion in the field. QA must cover offline simulation, partial connectivity, and cache staleness scenarios.
Implementation requires a dedicated offline search repository layer that abstracts the data source (remote Supabase vs. local SQLite/Hive cache) from the search screen. The cache schema must mirror the contact model but explicitly exclude fields tagged for field-level encryption — this requires a documented field exclusion list tied to the encryption configuration, not hardcoded field names. Background sync must use a connectivity-aware scheduler (e.g., WorkManager on Android, BGTaskScheduler on iOS) that triggers differential sync using a server-side `updated_at` cursor to minimize data transfer.
The search screen fallback logic must be transparent: same query interface, same result shape, with an injected offline indicator in the UI layer only. Performance target of 500ms for offline queries requires indexed local storage — ensure the cache table has indexes on searchable fields (name, phone). Edge cases include: first-run with no prior sync (show informative empty state, not an error), partial sync interrupted mid-flight, and encrypted field re-appearance if encryption config changes. Write integration tests covering offline simulation and sync trigger behavior.
Acceptance Criteria
- Given the device has no internet connection, when the coordinator searches for a contact by name, then results are returned from the local cache within 500ms
- Given offline search results are displayed, when the list is rendered, then a persistent banner or indicator communicates that results are from local cache and may not be fully up to date
- Given the device regains internet connectivity, when the cache sync service runs, then the local cache is updated with any server-side changes since the last sync
- Given a contact record contains encrypted sensitive fields, when that record is cached locally, then the encrypted fields are excluded from the local cache
- Given the local cache is empty (first-time use with no prior sync), when the device is offline and a search is performed, then an informative empty state explains that data must be synced first
Business Value
Field-based peer mentoring work frequently occurs in low-connectivity environments. An offline-capable search removes a hard dependency on internet access for core coordination tasks, ensuring that coordinators can look up contact details and history during home visits, in rural chapters, or while traveling between locations. This is particularly critical for Blindeforbundet, which emphasizes home visit workflows, and for NHF and HLF chapters in geographically dispersed areas.
Components
- Contact Search Screen ui
- Contact Search Service service
- Offline Contact Search Repository data
- Contact Cache Sync Repository data
- Search Debounce Utility infrastructure
- Field Encryption Utilities infrastructure