ADR 0008: Mapbox + @rnmapbox/maps over Google Maps

Status: Accepted
Date: 2026-04-19
Deciders: Ideony team

Context

Ideony’s booking flow and SOS dispatch require maps (service location, professional route), geocoding, directions, and distance matrix (live tracking tier 2: polyline on accept + redraw at >200 m, ~3 API calls/dispatch). The original plan used react-native-maps + Google Maps APIs. As of the UX overhaul sprint, a custom map style aligned with the Italian Sole brand palette was needed.

Decision

Replace react-native-maps + Google Maps with @rnmapbox/maps + Mapbox APIs (Geocoding, Directions, Matrix, Places) as a Day 1 decision. A custom Sole-palette map style is created via Mapbox Studio. Free tier covers 50K MAU + 100K API requests/month.

Consequences

Custom Mapbox Studio styles enable the Italian Sole palette on the map surface (terracotta roads, cream background).
Free tier (50K MAU / 100K req/mo) covers MVP 0 load without billing.
Mapbox Directions and Matrix APIs support SOS live tracking with polyline rendering.
Single vendor for all map primitives (tiles, geocoding, routing, places).

Mapbox requires a token exposed in the app bundle; token scoping and domain restriction required.
@rnmapbox/maps requires native rebuild on SDK version changes; no Expo Go support.
Pro nav (turn-by-turn) uses OS deep-link chooser (Apple Maps / Google / Waze) rather than in-app Mapbox navigation to avoid Mapbox Navigation SDK licensing cost.

Alternatives considered

react-native-maps + Google Maps — rejected: no custom style support matching Italian Sole palette; Google Maps pricing unpredictable at scale; Maps SDK for React Native is less actively maintained.
Apple MapKit — rejected: iOS-only; no Android equivalent in React Native.