Implement MapProviderIntegration SDK abstraction
epic-geographic-peer-mentor-map-data-infrastructure-task-010 — Implement the MapProviderIntegration class that wraps flutter_map behind a provider-agnostic interface. Expose buildMapWidget(center, zoom, markers, onBoundsChanged) returning a Flutter Widget, and a getBoundsFromController() method returning LatLngBounds. The abstraction allows swapping map providers without touching callers. Register an OpenStreetMap-backed implementation via Riverpod.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Define a sealed abstract class MapProviderIntegration (or Dart abstract interface) in lib/map/map_provider_integration.dart. Use a value object MapMarker (id, lat, lng, label) as the marker type so no flutter_map LatLng leaks. Inside OpenStreetMapProviderIntegration, hold a MapController internally and expose only LatLngBounds through getBoundsFromController(). Register via Riverpod: final mapProviderIntegrationProvider = Provider
Use a ChangeNotifierProvider or StateNotifierProvider if the controller needs lifecycle management. Debounce the onBoundsChanged callback using a Timer in the listener to avoid flooding the BLoC with events on every frame during pan. Consider using flutter_map's MapEventMoveEnd instead of continuous stream events.
Testing Requirements
Unit tests using flutter_test and Mockito: (1) verify buildMapWidget returns a non-null Widget; (2) mock onBoundsChanged and assert it is called after simulated pan; (3) assert getBoundsFromController returns valid bounds. Widget tests with pumpWidget: render the abstraction widget and verify no RenderFlex overflow or null-check errors occur. Abstraction boundary test: import the caller module and confirm no flutter_map symbols are present in its import graph. Riverpod override test: override mapProviderIntegrationProvider with a MockMapProviderIntegration and verify callers receive the mock.
Minimum 80% line coverage on the integration class itself.
Supabase's hosted PostGIS extension behaviour may differ from the local emulator for spatial RPC functions, causing bounding-box queries to return incorrect results or fail in production while passing locally.
Mitigation & Contingency
Mitigation: Write integration tests against the Supabase emulator from the start and run the same test suite against a staging Supabase project before merging. Use ST_DWithin and ST_MakeEnvelope in plain SQL first, validate with psql, then wrap as RPC.
Contingency: If PostGIS RPC proves unreliable, fall back to client-side bounding box filtering on a full fetch of consented mentor locations (acceptable for up to ~200 mentors per chapter) until the spatial query is stabilised.
OpenStreetMap tile usage may require attribution handling and rate limiting. Switching to Google Maps Flutter plugin mid-implementation would require significant rework of the map-provider-integration abstraction.
Mitigation & Contingency
Mitigation: Define the map-provider-integration abstraction interface before selecting the SDK so that the concrete implementation is swappable. Implement OSM first with correct attribution. Document Google Maps as the alternate with its API key setup steps.
Contingency: If OSM tiles are rejected by stakeholders or tile server limits are hit, activate the Google Maps Flutter plugin implementation behind the same interface without touching any UI or service code.
Incorrect RLS configuration could allow a coordinator to query mentor locations from a different organisation, constituting a GDPR data breach.
Mitigation & Contingency
Mitigation: Write dedicated RLS integration tests with two isolated test organisations and assert that cross-organisation queries return zero rows. Include these tests in CI. Have a second developer review all RLS policy SQL before migration is applied.
Contingency: If a cross-organisation data leak is discovered post-deployment, immediately disable the map feature via the organisation feature flag, revoke the affected Supabase RLS policy, and notify the data protection officer per the organisation's GDPR incident response procedure.