Native GPS Map for Taxi App

Subject: Build an in-app “Map + GPS + Turn-by-Turn Navigation” module for a Flutter TVDE app (Portugal)

⸻

1) Goal

Deliver a production-grade, in-app navigation module (turn-by-turn) using Mapbox, integrated with our Flutter app: map display, traffic-aware routing, automatic rerouting, Portuguese (pt-PT) voice guidance, robust GPS tracking (foreground/background), and geocoding/search restricted to Portugal.

⸻

2) Stack
• Flutter (UI/State)
• Native modules: Android (Kotlin), iOS (Swift)
• Mapbox Navigation + Maps + Geocoding/Search
• Flutter ↔ Native via MethodChannel/EventChannel

(Mapbox account/tokens provided by us.)

⸻

3) Functional Scope

3.1 Map & Route UI
• Map view, origin/destination/driver markers, route line, instruction banners, auto camera.

3.2 Turn-by-Turn Navigation
• Live traffic, automatic reroute, pt-PT voice guidance (mute/unmute), dynamic ETA & distance remaining.

3.3 GPS Tracking
• Stable foreground/background tracking (Android Foreground Service; iOS background location modes).
• Foreground update ~1s, background adaptive (5–15s).
• Accuracy target ≤ 10m; fallback logic for low accuracy.

3.4 Geocoding/Search
• Restricted to country=PT, configurable bbox (e.g., Coimbra), proximity=user.
• Limit types=address,place.
• Autocomplete with session tokens.

3.5 Flutter Bridge (Contract)
• MethodChannel tapsi/navigation
• initNavigation({voiceLang, units})
• setRoute({origin:{lat,lng}, destination:{lat,lng}, waypoints:[...]})
• startNavigation({simulate:false}), stopNavigation()
• muteVoice(), unmuteVoice()
• EventChannel tapsi/navigation_events
• onProgress({lat,lng,etaSeconds,distanceRemainingMeters,speed})
• onReroute({reason}), onArrival(), onError({code,message})

3.6 Offline/Connectivity
• Minimal tile cache for current route.
• Retry strategies for network loss.
• Keep last route active until reconnect.

3.7 Optional Fallback
• Deep-link to Google Maps/Waze (user-selectable fallback).

⸻

4) Non-Functional Requirements
• Performance: navigation start ≤ 2.5s after setRoute; reroute ≤ 2s typical.
• Battery: ≤ 8%/hour drain during continuous nav on mid-range devices.
• Stability: ≥ 99.9% crash-free rate in pilot.
• Privacy/GDPR: no token logging; opt-in/out for background tracking; secure key storage.
• Accessibility: dynamic font sizes; screen-reader friendly announcements.

⸻

5) Deliverables
1. Full native source (Kotlin/Swift) + minimal Flutter sample for testing.
2. Build setup (Gradle/SPM), Manifest/Info.plist, permissions, and token/auth setup notes.
3. Documentation: integration guide, channel contracts & data schemas, release checklists.
4. Tests: simulation mode (simulate=true) + field test around Coimbra (e.g., origin 40.211,-8.429 → destination 40.205,-8.410).
5. Debug screen for route setting, start/stop navigation, and viewing logs.

⸻

6) Acceptance Criteria
• In-app turn-by-turn navigation with pt-PT voice, ETA/distance updates, and automatic reroute.
• Correct event streaming to Flutter (onProgress/onArrival/onReroute/onError).
• Geocoding returns Portugal-only results (validated with ambiguous addresses).
• Stable background tracking (≥10 minutes with screen off, no data loss).
• Meets performance/battery targets; clean, reviewed code.

⸻

7) Timeline (Maximum 2 Weeks)

The full project must be delivered within 14 calendar days. Suggested milestones:
• Week 1:
• Flutter ↔ Native channels skeleton (MethodChannel/EventChannel)
• Map display + route drawing
• Simulated navigation progress events
• Week 2:
• Full integration with Mapbox Navigation SDK (Android/iOS)
• Turn-by-turn with pt-PT voice guidance
• Automatic reroute + live traffic
• Background tracking + PT-restricted geocoding/autocomplete
• Debug screen + documentation + final QA

Deliverables and payments tied to milestone acceptance.
Maximum timeline: 2 weeks total (no extensions beyond 14 days).

⸻

8) IP & Licensing
• All code/work product is owned by us.
• Third-party SDKs under their respective licenses; keys handled securely.

⸻

9) Post-Delivery Support
• 30 days of critical bug-fix support with ≤ 24h response time.
• Option to extend contract for maintenance/future phases.