Contact List Service
Component Detail
Description
Business logic layer that fetches and filters the contact list based on the authenticated user's role. Delegates to the contact repository and applies role-specific filtering rules — coordinators see their assigned members and peer mentors, org admins see all contacts, peer mentors see their assigned members only.
contact-list-service
Summaries
The Contact List Service ensures that every user sees exactly — and only — the contacts they are authorized to view, based on their organizational role. This role-gated visibility protects member privacy, reduces compliance risk, and prevents coordinators or peer mentors from accessing data outside their scope. For the organization, this means confident deployment across different role types without manual data segmentation. It also enables the product to scale to larger organizations with complex role hierarchies without rearchitecting access control, protecting the platform's long-term commercial viability and reducing support burden from accidental data exposure incidents.
Contact List Service is a medium-complexity backend logic layer with dependencies on two other components: contact-repository and contact-search-service, both of which must be completed and tested before this service can be fully integrated. The role-based filtering logic — three distinct access patterns for coordinators, org admins, and peer mentors — introduces branching complexity that requires thorough scenario-based testing for each role. Pagination handling adds an additional implementation surface that needs scope agreement early. Plan for at least one dedicated QA cycle covering all role permutations.
Changes to role definitions upstream will cascade into this service, so role schema changes should be flagged as a dependency risk throughout the project.
ContactListService is the business logic orchestrator for contact retrieval, sitting between the Riverpod provider layer and the repository/search layers. It exposes role-aware methods such as `getContactsForRole(UserRole role, String orgId)` and `searchContacts(...)`, internally branching on `UserRole` to construct the correct query scope before delegating to `ContactRepository`. Search operations are routed to `ContactSearchService`, which handles both local and remote strategies. The service does not own state — it is a pure functional layer returning typed results.
Pagination should be implemented via cursor-based offsets passed through to the repository. Unit tests should mock both dependencies and assert correct branching for all three role types. Avoid embedding raw Supabase query logic here — keep that in the repository.
Responsibilities
- Determine correct contact subset based on user role
- Apply role-based filtering rules before returning results
- Coordinate with search service for name and notes filtering
- Handle pagination or full-list fetch depending on list size
Interfaces
getContactsForRole(UserRole role, String orgId)
getPeerMentorsForRole(UserRole role, String orgId)
searchContacts(String query, UserRole role, String orgId)
searchPeerMentors(String query, UserRole role, String orgId)
getContactById(String contactId)
refreshContacts()
Relationships
Dependencies (2)
Components this component depends on
Related Data Entities (2)
Data entities managed by this component