Supabase Contact Search Repository
Component Detail
Description
Executes debounced ilike queries against the Supabase contacts and notes tables, searching by name, organization affiliation, and notes keywords. Returns typed contact and peer mentor result objects.
supabase-search-repository
Summaries
The Supabase Contact Search Repository is the gateway to the organization's live, authoritative contact data. It enables real-time discovery of colleagues, partners, and peer mentors using flexible search across names, organizational affiliations, and relationship notes — capabilities that drive meaningful professional connections. By enforcing organization-scoped and role-based filtering at the query level, the component protects data privacy and ensures users only surface contacts they are authorized to see, reducing compliance and data governance risk. Fast, accurate search directly correlates with user trust in the platform as a reliable professional network tool, supporting adoption and long-term retention goals.
This repository has no internal component dependencies, making it independently developable against a Supabase staging environment from the start of the sprint. However, it is a hard dependency for the Contact Search Service, so delays here directly delay integration testing for the search feature.
Delivery requires the Supabase schema for contacts, notes, and organizations to be finalized before query development begins — coordinate with the backend team on schema stability. Testing must cover: successful ilike queries, organization-scoped filtering, network error handling with typed exceptions, and cancellation of in-flight queries via `cancelPendingQuery()`. Performance testing should validate query latency under realistic dataset sizes with proper Supabase indexing on name and organization fields.
Supabase Contact Search Repository uses the Supabase Flutter client to execute `ilike` pattern-match queries against the `contacts` and `notes` tables. The `searchContacts(String query, String orgId)` method builds a Supabase query with `.ilike('name', '%$query%').eq('org_id', orgId)`, optionally chaining role-based filters derived from the authenticated user's claims. `searchNotes(String query, String orgId)` performs keyword matching on the `content` field of the notes table, joining back to contact IDs. Results are mapped to typed `Contact` and `PeerMentor` domain models using a dedicated mapper class — no raw maps leak into the service layer.
`cancelPendingQuery()` calls `.abort()` on the active query reference to prevent stale response delivery. Network errors from the Supabase client are caught and re-thrown as domain-specific `SearchException` subtypes (e.g., `NetworkSearchException`, `PermissionSearchException`) for clean handling upstream.
Responsibilities
- Execute ilike queries on name, organization, and notes fields
- Apply role-based and organization-scoped filters
- Map Supabase rows to domain contact models
- Handle network errors with typed exceptions
Interfaces
searchContacts(String query, String orgId)
searchNotes(String query, String orgId)
searchByOrganization(String orgName)
cancelPendingQuery()