# ahmed-habeeb/live_tracking_map architecture

> Architecture diagram of the GitHub repository ahmed-habeeb/live_tracking_map, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahmed-habeeb/live_tracking_map
- Repository: https://github.com/ahmed-habeeb/live_tracking_map

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TB
    Pub["live_tracking_map.dart\n(Public Entry)"]:::entry

    subgraph "UI Layer"
        Widget["LiveTrackingMapWidget"]:::ui
        Markers["MapMarkersBuilder"]:::ui
        Polylines["MapPolylinesBuilder"]:::ui
        Overlay["NavigationStatusOverlay"]:::ui
    end

    subgraph "Controller Layer"
        NavCtrl["NavigationController"]:::ctrl
        AnimCtrl["MapAnimationController"]:::ctrl
    end

    subgraph "Service Layer"
        ILoc["ILocationService"]:::service
        Loc["LocationService"]:::service
        IRoute["IRouteService"]:::service
        RouteServ["RouteService"]:::service
    end

    subgraph "MapService Adapters"
        MapServ["MapService"]:::adapter
        GMapServ["GoogleMapService"]:::adapter
        OsrmServ["OsrmMapService"]:::adapter
    end

    subgraph "API Client Layer"
        ApiCl["ApiClient"]:::api
        BaseDio["BaseDio"]:::api
        DioFac["DioFactory"]:::api
        ErrHandler["ErrorHandler"]:::api
        RespModel["ResponseModel"]:::api
    end

    subgraph "Domain Models"
        RouteSeg["RouteSegment"]:::model
        NavState["NavigationState"]:::model
        TrackConfMod["TrackingConfiguration"]:::model
        Enums["Enums"]:::model
        NavEx["NavigationException"]:::model
    end

    subgraph "External/Platform"
        DeviceLoc(("Device Location API")):::external
        GoogleMapsPlug(("Google Maps\nFlutter Plugin")):::external
        DirectionsAPI(("Google Directions API")):::external
        OSRMServer(("OSRM Server")):::external
        Internet(("Internet")):::external
    end

    subgraph "Tests"
        Test["live_tracking_map_test.dart"]:::test
    end

    Pub --> Widget
    Widget --> NavCtrl
    Widget --> AnimCtrl
    Widget --> Overlay
    Widget --> Polylines
    Widget --> Markers

    NavCtrl --> ILoc
    ILoc --> Loc
    DeviceLoc --> ILoc

    NavCtrl --> IRoute
    IRoute --> RouteServ
    RouteServ --> MapServ
    MapServ --> GMapServ
    MapServ --> OsrmServ
    GMapServ --> DirectionsAPI
    OsrmServ --> OSRMServer

    RouteServ --> ApiCl
    ApiCl --> BaseDio
    ApiCl --> DioFac
    ApiCl --> ErrHandler
    ApiCl --> RespModel
    RespModel --> RouteServ

    NavCtrl --> AnimCtrl
    AnimCtrl --> Widget

    ApiCl --> Internet
    GMapServ -.-> GoogleMapsPlug

    Pub --> Test

    classDef entry fill:#f9f,stroke:#333,stroke-width:1px
    classDef ui fill:#bbf,stroke:#333,stroke-width:1px
    classDef ctrl fill:#bfb,stroke:#333,stroke-width:1px
    classDef service fill:#f90,stroke:#333,stroke-width:1px
    classDef adapter fill:#f90,stroke:#333,stroke-width:1px
    classDef api fill:#ff9,stroke:#333,stroke-width:1px
    classDef model fill:#ddd,stroke:#333,stroke-width:1px
    classDef external fill:#f99,stroke:#333,stroke-width:1px
    classDef test fill:#eef,stroke:#333,stroke-width:1px

    click Pub "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/live_tracking_map.dart"
    click Widget "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/ui/widgets/live_tracking_map_widget.dart"
    click Markers "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/ui/widgets/map_markers_builder.dart"
    click Polylines "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/ui/widgets/map_polylines_builder.dart"
    click Overlay "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/ui/widgets/navigation_status_overlay.dart"
    click NavCtrl "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/ui/controller/navigation_controller.dart"
    click AnimCtrl "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/ui/controller/map_animation_controller.dart"
    click ILoc "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/services/loctaion_service/ilocation_service.dart"
    click Loc "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/services/loctaion_service/location_service.dart"
    click IRoute "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/services/route_service/iroute_service.dart"
    click RouteServ "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/services/route_service/route_service.dart"
    click ApiCl "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/api/api_client/api_client.dart"
    click BaseDio "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/api/api_client/base_dio.dart"
    click DioFac "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/api/dio/dio_factory.dart"
    click ErrHandler "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/api/error_handler/api_error_handler.dart"
    click RespModel "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/api/model/response_model.dart"
    click MapServ "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/map_service/map_service.dart"
    click GMapServ "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/map_service/google_map_service.dart"
    click OsrmServ "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/map_service/osrm_map_service.dart"
    click RouteSeg "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/models/route_segment.dart"
    click NavState "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/models/navigation_state.dart"
    click TrackConfMod "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/models/tracking_configuration.dart"
    click Enums "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/models/enums.dart"
    click NavEx "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/models/navigation_execption.dart"
    click TrackConfMod "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/lib/src/tracking_config.dart"
    click Test "https://github.com/ahmed-habeeb/live_tracking_map/blob/main/test/live_tracking_map_test.dart"
```
