Filter Search Results by Contact Type and Chapter
In organizations like NHF with up to 1,400 local chapters, or when a coordinator oversees multiple chapters, a simple name search can return many results from different contexts. Filter controls on the search screen allow the coordinator to scope results to a specific chapter, to only peer mentors or only contacts, or to a specific assignment status. These filters are applied client-side where possible and pushed as query parameters to the repository layer for database-level filtering, ensuring performance at scale. The chapter filter also prevents the coordinator from accidentally acting on contacts outside their permitted scope.
User Story
Audience Summaries
For organizations operating at the scale of NHF—with up to 1,400 local chapters and complex regional hierarchies—unfiltered search results create operational confusion and introduce data privacy risk by surfacing contacts from chapters outside a coordinator's legitimate scope. Filter controls by contact type and chapter affiliation directly address these risks while enabling coordinators managing multi-chapter responsibilities to work with precision and confidence. The business value is both defensive and offensive: defensively, filtering enforces the data boundary expectations that Norwegian privacy regulations and organizational trust require; offensively, it enables coordinators to identify peer mentor availability or contact need within specific chapter contexts, accelerating match-making and follow-up workflows. For Blindeforbundet's geographic matching requirements, chapter-scoped filtering is a prerequisite for the platform to be operationally viable.
Delivering this story strengthens the platform's value proposition across all three target organizations by demonstrating that it handles real-world organizational complexity rather than only simple single-chapter use cases.
This high-priority story depends on the foundational contact search story and must be sequenced after that baseline is stable. Delivery complexity is moderate: the filter UI (contact type chips, chapter selector, dismissible active filter display) is straightforward but must be coordinated with the repository layer to ensure filters translate correctly to database query parameters rather than remaining client-side only—a distinction critical for performance at NHF's scale. The edge case where a coordinator has access to only one chapter (auto-defaulted, disabled filter) requires explicit product decision sign-off to confirm the intended UX. QA must cover six acceptance criteria including multi-filter combination behavior, chip dismissal and re-query flow, and the single-chapter default state.
Stakeholder involvement from NHF is advisable given their unique hierarchical complexity. Cross-functional dependency exists with the backend team confirming that chapter affiliation is a queryable, indexed field in Supabase. Rollout can be feature-flagged per organization to manage the varying complexity of each client's chapter structure during initial deployment.
Filter implementation spans two layers: a client-side filter state manager that maintains active filter selections as dismissible chip state, and a repository-layer query builder that translates those selections into Supabase query parameters (e.g., `.eq('chapter_id', selectedChapterId)`, `.eq('contact_type', selectedType)`). Critically, chapter-level filtering must be enforced at the database query level—not purely client-side—to prevent over-fetching and potential data leakage when a coordinator's RLS scope theoretically permits broader access than their operational context requires. The chapter filter must be populated dynamically from the coordinator's permitted chapters list, not hardcoded, and the single-chapter auto-default case requires conditional rendering of the filter control as disabled. Multi-filter combinations must compose as AND conditions in the query.
Active filter chips must be rendered above the results list with individual dismiss handlers that trigger a re-query with the updated filter set. Performance consideration: for NHF's scale, ensure chapter_id and contact_type columns are indexed in Supabase. Integration tests must cover the disabled-filter single-chapter edge case, multi-filter AND composition, and chip dismissal triggering correct query re-execution.
Acceptance Criteria
- Given the coordinator is on the search screen, when they tap a filter control, then filter options appear for contact type (peer mentor / contact) and chapter affiliation
- Given a chapter filter is selected, when the search query is executed, then only contacts affiliated with that chapter appear in results
- Given a contact type filter is selected, when results are displayed, then only the selected contact type appears, and the active filter is visually indicated
- Given multiple filters are active, when results are displayed, then all active filters are shown as dismissible chips above the results list
- Given a filter chip is dismissed, when the search re-executes, then results update to reflect the removed filter
- Given the coordinator has access to only one chapter, when the chapter filter is shown, then it defaults to that chapter and the filter control is disabled
Business Value
NHF's complex hierarchy (12 national associations, 9 regions, 1,400 local chapters) and Blindeforbundet's geographic matching requirements mean that unfiltered search results create confusion and risk of cross-chapter data leakage. Filtering is essential for coordinators managing multi-chapter scopes to maintain operational clarity, uphold data privacy requirements, and act decisively on the correct contact subset.