How ahmed-habeeb/live_tracking_map works
Project Type and Purpose
• This is a Flutter client-side library (“live_tracking_map”) that exposes a customizable widget for real-time location tracking, route visualization, turn-by-turn navigation, off-route detection, ETA updates, and map rendering.
• It is *not* a full-stack app with its own backend; it is an embeddable Flutter package that integrates with device location services and external routing APIs (Google Directions API or an OSRM server).
File Structure Analysis
• lib/live_tracking_map.dart: Public entry-point exporting the widget and key classes.
• lib/src/api:
• api_client/ (ApiClient, BaseDio) → HTTP client layer built on Dio
• dio_factory → configures Dio instances
• error_handler → centralized API error handling
• model → response_model for parsing JSON payloads
• lib/src/map_service: Abstract MapService + two implementations (GoogleMapService, OsrmMapService) for routing calls.
• lib/src/models: Domain models and enums (RouteSegment, NavigationState, TrackingConfiguration, etc.)
• lib/src/services:
• location_service → ILocationService, LocationService (device or custom)
• route_service → IRouteService, RouteService (drives routing logic on top of MapService + API layer)
• lib/src/ui:
• controller → MapAnimationController, NavigationController
• widgets → LiveTrackingMapWidget, builders for markers/polylines, navigation status overlay
• lib/src/tracking_config.dart: high-level configuration object for the package
• tests: Unit test illustrating API and widget behavior
Key Insights from README
• Exposes a single LiveTrackingMapWidget for both automatic and manual location modes.
• Supports two map/routing backends: Google Maps (via API key) and OSRM.
• Offers callbacks for route updates, distance, and ETA.
Main Components
a. UI Layer
• LiveTrackingMapWidget
• Sub-widgets: MapMarkersBuilder, MapPolylinesBuilder, NavigationStatusOverlay
b. Controller Layer
• NavigationController (orchestrates route logic, off-route detection)
• MapAnimationController (animates markers, camera)
c. Service Layer (Domain Services)
• ILocationService → LocationService (device GPS or custom provider)
• IRouteService → RouteService (computes routes off of MapService + API)
d. API Client Layer
• ApiClient (BaseDio + DioFactory) → handles HTTP calls
• ErrorHandler
• ResponseModel parser
e. MapService Adapters
• GoogleMapService
• OsrmMapService
• Underneath these, external systems: Google Directions API or OSRM server
f. Models
• RouteSegment, NavigationState, TrackingConfiguration, etc.
g. External & Platform Services
• Device Location API
• Google Maps Flutter plugin (rendering)
• Internet → API endpoints
Relationships and Data Flow
• Device Location → ILocationService → NavigationController
• NavigationController → IRouteService → MapService → ApiClient → External API
• ApiClient ←→ ResponseModel → RouteService
• RouteService → NavigationController → returns route points, ETA, distance
• NavigationController → MapAnimationController → LiveTrackingMapWidget (UI)
• UI sends user interactions (e.g., manual location updates) back into controllers/services
Architectural Patterns & Principles
• Hexagonal / Ports & Adapters: Interfaces (ILocationService, IRouteService, MapService) decouple core logic from implementations (device GPS vs. custom, Google vs. OSRM).
• MVC-style separation: Widgets (View) ←→ Controllers (Presenter) ←→ Services/Models (Model)
• Dependency Injection: Services and map adapters are passed into widget constructors.
• Single Responsibility: Each package sub-directory focuses on a single concern (API, map integration, UI, domain models).