Geographic Match Service
Component Detail
Description
Server-side service that ranks eligible peer mentors by proximity to a contact's registered location using Haversine distance computation. Applies eligibility filters (active status, org membership, module-enabled) before distance ranking, and returns a graceful fallback of unranked eligible mentors when location data is absent. All location lookups are recorded in the organization audit log.
geographic-match-service
Sources & reasoning
Core algorithmic service required to implement proximity-based mentor ranking. The feature is entirely a service-layer capability - no dedicated UI beyond surfacing the ranked list in the existing assignment dispatch flow. Haversine computation, eligibility filtering, audit logging, and module-gate enforcement are all backend concerns scoped to this service.
No source references — this artifact was included based on reasoning alone (see above).
Responsibilities
- Fetch candidate peer mentors scoped to the contact's organization and filter by active status and module-enabled flag
- Compute Haversine distances between contact location and each candidate's peer_mentor_locations record
- Return ranked suggestion list via GET /api/v1/assignments/:id/suggested-mentors
- Enforce geographic-map-view module toggle - return 403 when module is disabled for the tenant
- Write location lookup audit events to the organization audit log
Interfaces
getRankedMentorSuggestions(assignmentId: string): Promise<RankedMentorSuggestion[]>
computeHaversineDistance(lat1: number, lon1: number, lat2: number, lon2: number): number
applyEligibilityFilters(mentors: PeerMentor[], orgId: string): Promise<PeerMentor[]>
getFallbackUnrankedList(assignmentId: string): Promise<PeerMentor[]>
logLocationLookupAuditEvent(orgId: string, assignmentId: string, actorId: string): Promise<void>
checkModuleEnabled(orgId: string): Promise<boolean>
Relationships
Dependencies (4)
Components this component depends on
Related Data Entities (4)
Data entities managed by this component