Geographic Matching & Map View
Feature Detail
Description
This feature provides coordinators with an interactive map view of peer mentor locations to support geographic matching of mentors to assignment requests, particularly in large counties where Blindeforbundet operates. Peer mentor location pins are displayed on a map with availability status indicators, allowing coordinators to identify the closest available qualified mentor for a given assignment location. The location repository stores peer mentor home areas (not real-time GPS tracking) to protect privacy while still enabling effective geographic matching. The map view integrates with the peer mentor profile feature to allow drill-down from a map pin to a full mentor profile.
Analysis
Geographic matching is a specific but operationally significant need for Blindeforbundet, which operates across large Norwegian counties where travel time is a meaningful factor in assignment quality and volunteer sustainability. Without a map-based overview, coordinators must mentally map postal codes to geography, which is error-prone and time-consuming, particularly for new coordinators unfamiliar with the local area. Improving matching accuracy reduces unnecessary travel for peer mentors, increasing volunteer satisfaction and retention. The feature also supports equitable distribution of assignments across a geographic area, preventing volunteer burnout from overloading mentors in densely populated zones while under-utilising mentors in quieter areas.
The map view is implemented using the flutter_map package with OpenStreetMap tiles to avoid Google Maps licensing costs and privacy concerns. Peer mentor locations are stored as municipality or postal code area centroids in the peer_mentor_locations table, with no real-time GPS tracking. Location data is only accessible to coordinators within the same organisation via RLS policies. Map pins use custom Flutter widgets with availability status colour coding matching the unified entity colour system. Clustering is implemented for dense areas using flutter_map_marker_cluster. Tapping a pin opens a bottom sheet with the peer mentor card widget and a navigation button to the full profile. The feature requires explicit opt-in from peer mentors for location storage, with clear privacy disclosure, to comply with GDPR requirements.
Dependencies
Definition of Done
Components (8)
User Stories (8)
As a As a Coordinator
I want I want to filter the map pins by availability status (available, paused, or all) using a filter bar at the top of the map
So that So that I can focus only on mentors who are currently available when matching an assignment, removing paused or inactive mentors from my visual decision space
- Given the map is showing all pins, when I tap the 'Available' filter chip, then only pins for mentors with active availability status are displayed and paused mentor pins are hidden
- Given I have selected the 'Available' filter, when I tap 'All', then all mentor pins reappear on the map
- Given I select a filter, when the map updates, then the transition completes within 1 second with no full page reload
- +1 more
As a As a Coordinator
I want I want to navigate from a map pin's bottom sheet directly to that mentor's full profile page
So that So that I can review the mentor's complete details — certifications, assignment history, skill areas, and contact information — before making a matching decision and dispatching an assignment
- Given I have tapped a mentor's map pin and the bottom sheet is open, when I tap 'View Full Profile', then I am navigated to the Peer Mentor Detail Screen for that specific mentor
- Given I am on the Peer Mentor Detail Screen reached via the map, when I press the back button, then I return to the map view with the same zoom level and centre position preserved
- Given I am on the mentor profile reached via the map, when I review the profile, then all certification, availability, and skill information is displayed accurately and reflects the current database state
As a As a Coordinator
I want I want to tap a location pin on the map and see a bottom sheet with the mentor's key details and availability status
So that So that I can quickly assess a mentor's suitability for an assignment without leaving the map view, maintaining my geographic context while reviewing candidate details
- Given the map is displaying pins, when I tap a single mentor pin, then a bottom sheet slides up within 300ms showing the mentor's name, availability status, and a 'View Full Profile' button
- Given the bottom sheet is open, when I tap 'View Full Profile', then I am navigated to that mentor's full profile screen
- Given the bottom sheet is open, when I swipe it down or tap outside it, then it dismisses and the map returns to its previous position and zoom level
- +1 more
As a As a Coordinator
I want I want each location pin on the map to be colour-coded to reflect the mentor's current availability status using the unified entity colour system
So that So that I can instantly distinguish available, paused, and inactive mentors on the map at a glance without tapping each pin individually
- Given the map is loaded, when I view the pins, then available mentors have a distinct colour, paused mentors have a different colour, and the colour coding matches the unified entity colour system
- Given a mentor's availability status changes (e.g., a pause is set), when I next view the map, then that mentor's pin colour updates to reflect the new status within the next map load or real-time update cycle
- Given the map is displayed, when I look for a colour legend, then a visible legend or tooltip explains what each pin colour represents
- +1 more
As a As a Coordinator
I want I want to open a map view that displays location pins for all peer mentors within my organisational area
So that So that I can quickly understand the geographic distribution of my mentor pool and identify who is closest to a given assignment location without manually mapping postal codes
- Given I am authenticated as a coordinator, when I navigate to the map view, then the map renders within 3 seconds with all peer mentor location pins visible for my organisational scope
- Given the map has loaded, when I zoom or pan the map, then pins reposition fluidly and clustered groups split into individual pins at sufficient zoom levels
- Given I have no peer mentors with stored location consent, when I open the map, then an empty-state message explains that no location data is available and prompts me to ensure mentors have opted in
- +1 more
As a As a Coordinator
I want I want the map to show me mentor pins ranked by proximity to a target assignment location so that I can identify the closest available qualified mentor
So that So that I can minimise travel time for peer mentors, improving volunteer satisfaction and reducing unnecessary travel burden — especially in large geographic counties
- Given I enter or select an assignment target location on the map, when the proximity calculation completes, then mentor pins are annotated or ranked to indicate relative distance from the target location
- Given proximity ranking is displayed, when I tap a ranked mentor pin, then the bottom sheet shows the estimated distance from the assignment location
- Given proximity is calculated using centroids, when I review results, then the distance shown is labelled as approximate (municipality/postal code level) to set accurate expectations
- +1 more
As a As a Coordinator
I want I want the map view to be accessible only to users with the coordinator role, with peer mentors unable to access location data for other mentors
So that So that sensitive location data about peer mentors is protected from unauthorised access and only those with a legitimate coordination need can view geographic distributions
- Given I am authenticated with a peer mentor role, when I attempt to navigate to the map view route, then I am redirected to the No-Access Screen and no location data is returned from the API
- Given I am authenticated as a coordinator, when I open the map view, then only mentor location pins within my own organisational scope are visible
- Given I am authenticated as a coordinator in Organisation A, when I view the map, then I cannot see pins for mentors belonging to Organisation B
- +1 more
As a As a Coordinator
I want I want the system to only display location data for peer mentors who have explicitly opted in to location storage via a clear GDPR consent flow
So that So that the organisation complies with GDPR requirements for personal location data and peer mentors trust that their location information is handled lawfully and transparently
- Given a peer mentor has not provided location consent, when I view the map as a coordinator, then no location pin is displayed for that mentor
- Given a peer mentor has consented, when I view the map, then their location pin is visible with availability colour coding
- Given a peer mentor withdraws consent, when their consent record is updated, then their pin is removed from the map for all coordinators within the next data refresh
- +2 more