Create ContactListRiverpodProvider with AsyncValue streams
epic-contact-list-management-business-logic-task-007 — Implement the ContactListRiverpodProvider using Riverpod's AsyncNotifier pattern. Expose two separate AsyncValue streams: one for the full role-scoped contact list and one for peer mentor contacts. Wire both streams to ContactListService, triggering fetches when the provider is first read. Handle loading, data, and error states with appropriate AsyncValue transitions.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 4 - 323 tasks
Can start after Tier 3 completes
Implementation Notes
Use `@riverpod` code generation (riverpod_generator) if the project already uses it — this enforces correct AsyncNotifier patterns and eliminates boilerplate errors. If not, use `AsyncNotifierProvider
Use `ref.onDispose()` to cancel any in-flight futures when the provider is disposed. For the peer mentor list: either derive it from the full list using a `FutureProvider.family` that filters, or fetch it separately in `build()` — the separate fetch approach is cleaner if peer mentor contacts are a distinct query.
Testing Requirements
Unit tests using ProviderContainer (riverpod_test package) to verify state transitions without UI. Test: initial state is AsyncValue.loading, then transitions to data after service resolves, then to error when service throws. Widget tests (flutter_test + WidgetTester) to verify UI responds correctly to each AsyncValue state. Mock ContactListService using Riverpod's overrideWithValue or a Mockito mock.
Test role-based peer mentor list population. Test provider invalidation triggers re-fetch. Aim for 100% coverage of state transition paths.
For organizations with large contact lists (NHF has 1,400 local chapters and potentially thousands of contacts), local in-memory filtering may be too slow and Supabase ILIKE queries without supporting indexes may exceed acceptable response times or accumulate excessive read costs, degrading search usability for power users.
Mitigation & Contingency
Mitigation: Define and document the list-size threshold in ContactSearchService before implementation. Confirm that indexes on name and notes columns exist in the Supabase schema before enabling server-side search. Profile ContactSearchService against realistic data volumes in the staging environment using the largest expected org.
Contingency: If response times are unacceptable in staging, introduce result-count pagination in ContactListService and add a user-visible 'showing top N results — refine your search' indicator, deferring full pagination to a follow-up task.
In NHF's multi-chapter context, when a user switches organization, Riverpod providers may emit a brief window of stale contact data scoped to the previous organization before the invalidation cycle completes, transiently exposing contacts from the wrong chapter.
Mitigation & Contingency
Mitigation: Model organization context as a Riverpod provider dependency so that any context change immediately marks contact providers as stale. Render a loading skeleton instead of the stale list during the re-fetch transition. Cover this scenario in integration tests with explicit org-switch sequences.
Contingency: If race conditions are observed during QA, add an explicit organization_id equality check in ContactListService that compares each fetched record's scope to the active session org, discarding any mismatched batch before returning results to the provider.