🏠 Overview › ✅ Implementation Tasks ›✅ epic-geographic-peer-mentor-map-data-infrastructure-task-009

Add flutter_map and OpenStreetMap dependencies

epic-geographic-peer-mentor-map-data-infrastructure-task-009 — Add flutter_map and latlong2 packages to pubspec.yaml. Configure the OpenStreetMap tile URL template, attribution string, and fallback tile error handler. Verify the package versions are compatible with the existing Flutter SDK version and that OSM tile usage complies with the OSM tile usage policy for the expected request volume.

high priority low complexity infrastructure pending infrastructure specialist Tier 0

Acceptance Criteria

flutter_map package added to pubspec.yaml dependencies at the latest stable version compatible with the project's Flutter SDK constraint
latlong2 package added to pubspec.yaml dependencies (required by flutter_map for LatLng and LatLngBounds types)
flutter pub get runs without version conflicts against existing dependencies (bloc, riverpod, supabase_flutter, etc.)
A MapConfig class or constants file defines the OSM tile URL template: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png'
The OSM attribution string is defined as a constant: '© OpenStreetMap contributors'
A TileLayer errorTileCallback is configured to log tile load failures without crashing the app
No API key or token is required or embedded for OSM raster tiles (public endpoint)
If expected tile request volume exceeds OSM's policy limit (~1M tiles/day for non-commercial apps), a note is added to the README or config file documenting the need to self-host tiles or use a commercial tile provider
flutter_map version is pinned to a specific minor version (e.g. ^6.0.0) to prevent silent breaking changes
The app builds successfully on both iOS and Android after adding the dependency (flutter build apk --debug and flutter build ios --debug --no-codesign pass)

Technical Requirements

frameworks
Flutter
flutter_map
latlong2
apis
OpenStreetMap Tile API (https://tile.openstreetmap.org/{z}/{x}/{y}.png)
performance requirements
Tile caching: configure flutter_map's built-in tile caching or add cached_network_image/flutter_map_tile_caching package to reduce redundant tile fetches on repeated map views
Limit initial map zoom level to avoid excessive tile requests on first render (start at zoom 10–12 for municipality-level view)
security requirements
OSM public tile endpoint requires no credentials — do not add any token or key to the tile URL
Tile requests will include the device's IP address — this is acceptable for map tiles but should be noted in the privacy policy as third-party data transfer
If Mapbox is considered as an alternative tile provider, the public access token (for tiles only) is acceptable in the app binary per Mapbox's security model — but the secret token must never be included
ui components
TileLayer (flutter_map)
FlutterMap widget

Execution Context

Execution Tier
Tier 0

Tier 0 - 440 tasks

Implementation Notes

Add to pubspec.yaml under dependencies: flutter_map: ^6.1.0 (verify latest at pub.dev/packages/flutter_map) and latlong2: ^0.9.0. The latlong2 version must match the one flutter_map depends on — check flutter_map's own pubspec.yaml if you get a version conflict. Create lib/features/map/config/map_config.dart with static constants: kOsmTileUrlTemplate, kOsmAttribution, kDefaultMapCenter (e.g. Oslo coordinates: LatLng(59.9139, 10.7522)), kDefaultZoom (10.0).

The OSM usage policy (https://operations.openstreetmap.org/policies/tiles) requires: valid HTTP User-Agent header, attribution displayed, caching enabled, no bulk downloading. Configure the TileLayer userAgentPackageName parameter with your app's package name (e.g. 'no.norskdigital.likepersonsapp') to comply. If the app is expected to scale beyond a few hundred daily active users, evaluate tile.openstreetmap.org versus a self-hosted tile server or commercial provider (Mapbox, Maptiler) — document this decision in the epic.

Testing Requirements

Smoke test: create a minimal MapScreen widget with FlutterMap + TileLayer pointing to OSM and verify tiles load in a Flutter integration test or manual device test. Verify flutter pub get produces no version conflicts by checking the pubspec.lock. Run flutter analyze to confirm no new lint errors from the added packages. Test on both iOS simulator and Android emulator to confirm the network request to OSM tile endpoint succeeds (check with Flutter DevTools network tab).

Test the errorTileCallback fires correctly by pointing the tile URL to an invalid endpoint in a test environment.

Component
Map Provider Integration
infrastructure high
Epic Risks (3)
high impact medium prob integration

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.

medium impact low prob dependency

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.

high impact low prob security

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.

Quick Links
All Tasks Execution Plan