# muhammedshibilm/speedometer-apk architecture

> Architecture diagram of the GitHub repository muhammedshibilm/speedometer-apk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muhammedshibilm/speedometer-apk
- Repository: https://github.com/muhammedshibilm/speedometer-apk

## Overview

#### Purpose and entry points
Speedy is a Flutter speedometer and trip-tracking app: it reads live GPS speed, supports HUD mirroring and themes, alerts on speed limits, and retains trip summaries. Flutter starts in `lib/main.dart`; application navigation is organized through `lib/pages/home_shell.dart`. Native launch hosts exist for Android (`android/app/src/main/kotlin/tech/muhammedshibilm/speedy/MainActivity.kt`) and iOS (`ios/Runner/AppDelegate.swift`).

#### Application shell and user flows
The main UI separates driving, trip history, settings, and first-run guidance into page-level boundaries:
- Drive session and real-time speed display: `lib/pages/drive_page.dart`
- Navigation/container shell: `lib/pages/home_shell.dart`
- Trip browsing: `lib/pages/trips_page.dart`
- User preferences and limits: `lib/pages/settings_page.dart`
- Onboarding/tutorial: `lib/pages/tutorial_page.dart`

The primary control flow is Drive Page → start trip/location permission → continuous location-derived speed updates → optional limit alert → end trip → name/store/display trip in history.

#### Driving-behavior pipeline
`lib/driving_behavior/behavior_provider.dart` is the state/control boundary for behavior analysis during a trip. It operates on structured detected events in `lib/driving_behavior/behavior_event_model.dart` and produces trip-level scoring through `lib/driving_behavior/trip_score.dart`. The README identifies GPS filtering, including Kalman filtering, as part of the live-speed accuracy path; this pipeline should remain distinct from UI rendering so that detection/scoring can evolve independently.

#### Data models and persistence boundary
Trip records are represented by `lib/models/trip_model.dart`; generated serialization support is present in `lib/models/trip_model.g.dart`. Behavior-event serialization similarly resides in `lib/driving_behavior/behavior_event_model.g.dart`. These model/generated-file pairs define the durable data boundary for trip history, including the README-described speed, distance, duration, and summary metrics. No remote backend or service integration is evidenced by the repository tree; data ownership appears client-side.

#### Preferences, alerts, and presentation state
Theme selection is managed separately in `lib/providers/theme_provider.dart`, allowing application-wide light/dark or system-driven appearance. Settings expose the speed-limit and alert-mode policy, while the driving screen consumes that policy to trigger vibration and/or sound behavior. The bundled alert audio asset is `assets/audio/over_limit.mp3`. HUD mode is a presentation transformation of the driving display, not a separate runtime.

#### Platform and runtime integration
The app targets Flutter-supported Android, iOS, web, Linux, macOS, and Windows runtimes. Android additionally includes a native home-screen widget provider at `android/app/src/main/kotlin/tech/muhammedshibilm/speedy/SpeedyWidgetProvider.kt`, backed by `android/app/src/main/res/layout/speedy_widget.xml` and widget metadata in `android/app/src/main/res/xml/speedy_widget_info.xml`. Platform projects primarily host Flutter; device location, permissions, vibration, and audio are material device-service boundaries required by the driving workflow.

Main entry points: [`lib/pages/home_shell.dart`](https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/pages/home_shell.dart) (Home shell), [`lib/pages/drive_page.dart`](https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/pages/drive_page.dart) (Drive page), [`lib/main.dart`](https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/main.dart) (Flutter entry point), [`lib/models/trip_model.dart`](https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/models/trip_model.dart) (Trip record)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flutter["Flutter app"]
  node_main(("Flutter entry point<br/>[main.dart]"))
  node_shell["Home shell<br/>navigation<br/>[home_shell.dart]"]
  node_drive["Drive page<br/>live driving UI<br/>[drive_page.dart]"]
  node_trips["Trips page<br/>history UI<br/>[trips_page.dart]"]
  node_settings["Settings page<br/>preferences UI<br/>[settings_page.dart]"]
  node_tutorial["Tutorial page<br/>onboarding UI<br/>[tutorial_page.dart]"]
  node_theme["Theme provider<br/>presentation state"]
  node_alert_audio["Over-limit audio<br/>audio asset<br/>[over_limit.mp3]"]
end

subgraph group_driving["Driving pipeline"]
  node_behavior["Behavior provider<br/>trip analysis control"]
  node_behavior_event["Behavior events<br/>event model"]
  node_trip_score["Trip score<br/>scoring model<br/>[trip_score.dart]"]
  node_trip_model["Trip record<br/>durable model<br/>[trip_model.dart]"]
  node_local_history[("Client-side trip history<br/>local persistence")]
  node_speed_filter["GPS speed filtering<br/>live-speed processing"]
  node_limit_alert["Speed-limit alerts<br/>device alert policy"]
end

subgraph group_platform["Platform integration"]
  node_location{{"Location and permissions<br/>device service"}}
  node_android_host["Android Flutter host<br/>native launch host<br/>[MainActivity.kt]"]
  node_ios_host["iOS Flutter host<br/>native launch host<br/>[AppDelegate.swift]"]
  node_android_widget["Android home widget<br/>native widget provider"]
end

node_android_host -->|"launches Flutter"| node_main
node_ios_host -->|"launches Flutter"| node_main
node_main -->|"starts app"| node_shell
node_shell -->|"driving tab"| node_drive
node_shell -->|"history tab"| node_trips
node_shell -->|"settings tab"| node_settings
node_shell -->|"first-run guidance"| node_tutorial
node_theme -->|"applies appearance"| node_shell
node_drive -->|"requests and receives GPS"| node_location
node_location -->|"location samples"| node_speed_filter
node_speed_filter -->|"live speed updates"| node_drive
node_speed_filter -->|"trip speed stream"| node_behavior
node_behavior -->|"detects"| node_behavior_event
node_behavior_event -->|"feeds scoring"| node_trip_score
node_trip_score -->|"trip summary"| node_trip_model
node_drive -->|"ends and names trip"| node_trip_model
node_trip_model -->|"serializes locally"| node_local_history
node_local_history -->|"loads records"| node_trips
node_settings -->|"configures limit and mode"| node_limit_alert
node_drive -->|"evaluates live speed"| node_limit_alert
node_limit_alert -->|"plays when enabled"| node_alert_audio
node_android_widget -.->|"Android app integration"| node_android_host

click node_main "https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/main.dart"
click node_shell "https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/pages/home_shell.dart"
click node_drive "https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/pages/drive_page.dart"
click node_trips "https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/pages/trips_page.dart"
click node_settings "https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/pages/settings_page.dart"
click node_tutorial "https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/pages/tutorial_page.dart"
click node_theme "https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/providers/theme_provider.dart"
click node_behavior "https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/driving_behavior/behavior_provider.dart"
click node_behavior_event "https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/driving_behavior/behavior_event_model.dart"
click node_trip_score "https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/driving_behavior/trip_score.dart"
click node_trip_model "https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/models/trip_model.dart"
click node_alert_audio "https://github.com/muhammedshibilm/speedometer-apk/blob/main/assets/audio/over_limit.mp3"
click node_android_host "https://github.com/muhammedshibilm/speedometer-apk/blob/main/android/app/src/main/kotlin/tech/muhammedshibilm/speedy/MainActivity.kt"
click node_ios_host "https://github.com/muhammedshibilm/speedometer-apk/blob/main/ios/Runner/AppDelegate.swift"
click node_android_widget "https://github.com/muhammedshibilm/speedometer-apk/blob/main/android/app/src/main/kotlin/tech/muhammedshibilm/speedy/SpeedyWidgetProvider.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_shell,node_drive,node_trips,node_settings,node_tutorial,node_theme,node_alert_audio toneBlue
class node_behavior,node_behavior_event,node_trip_score,node_trip_model,node_local_history,node_speed_filter,node_limit_alert toneAmber
class node_location,node_android_host,node_ios_host,node_android_widget toneMint
```

## Components

### Flutter app

- [Flutter entry point](https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/main.dart): entry point · `lib/main.dart`
- [Home shell](https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/pages/home_shell.dart): navigation · `lib/pages/home_shell.dart`
- [Drive page](https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/pages/drive_page.dart): live driving UI · `lib/pages/drive_page.dart`
- [Trips page](https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/pages/trips_page.dart): history UI · `lib/pages/trips_page.dart`
- [Settings page](https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/pages/settings_page.dart): preferences UI · `lib/pages/settings_page.dart`
- [Tutorial page](https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/pages/tutorial_page.dart): onboarding UI · `lib/pages/tutorial_page.dart`
- [Theme provider](https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/providers/theme_provider.dart): presentation state · `lib/providers/theme_provider.dart`
- [Over-limit audio](https://github.com/muhammedshibilm/speedometer-apk/blob/main/assets/audio/over_limit.mp3): audio asset · `assets/audio/over_limit.mp3`

### Driving pipeline

- [Behavior provider](https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/driving_behavior/behavior_provider.dart): trip analysis control · Coordinates driving-event analysis during a trip. · `lib/driving_behavior/behavior_provider.dart`
- [Behavior events](https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/driving_behavior/behavior_event_model.dart): event model · `lib/driving_behavior/behavior_event_model.dart`
- [Trip score](https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/driving_behavior/trip_score.dart): scoring model · `lib/driving_behavior/trip_score.dart`
- [Trip record](https://github.com/muhammedshibilm/speedometer-apk/blob/main/lib/models/trip_model.dart): durable model · Stores trip speed, distance, duration, and summary metrics. · `lib/models/trip_model.dart`
- **Client-side trip history**: local persistence · No remote backend is evidenced.
- **GPS speed filtering**: live-speed processing · Includes the documented Kalman filtering accuracy path.
- **Speed-limit alerts**: device alert policy · Applies vibration and/or sound according to settings.

### Platform integration

- **Location and permissions**: device service
- [Android Flutter host](https://github.com/muhammedshibilm/speedometer-apk/blob/main/android/app/src/main/kotlin/tech/muhammedshibilm/speedy/MainActivity.kt): native launch host · `android/app/src/main/kotlin/tech/muhammedshibilm/speedy/MainActivity.kt`
- [iOS Flutter host](https://github.com/muhammedshibilm/speedometer-apk/blob/main/ios/Runner/AppDelegate.swift): native launch host · `ios/Runner/AppDelegate.swift`
- [Android home widget](https://github.com/muhammedshibilm/speedometer-apk/blob/main/android/app/src/main/kotlin/tech/muhammedshibilm/speedy/SpeedyWidgetProvider.kt): native widget provider · `android/app/src/main/kotlin/tech/muhammedshibilm/speedy/SpeedyWidgetProvider.kt`

## Connections

- Android Flutter host → Flutter entry point: launches Flutter
- iOS Flutter host → Flutter entry point: launches Flutter
- Flutter entry point → Home shell: starts app
- Home shell → Drive page: driving tab
- Home shell → Trips page: history tab
- Home shell → Settings page: settings tab
- Home shell → Tutorial page: first-run guidance
- Theme provider → Home shell: applies appearance
- Drive page → Location and permissions: requests and receives GPS
- Location and permissions → GPS speed filtering: location samples
- GPS speed filtering → Drive page: live speed updates
- GPS speed filtering → Behavior provider: trip speed stream
- Behavior provider → Behavior events: detects
- Behavior events → Trip score: feeds scoring
- Trip score → Trip record: trip summary
- Drive page → Trip record: ends and names trip
- Trip record → Client-side trip history: serializes locally
- Client-side trip history → Trips page: loads records
- Settings page → Speed-limit alerts: configures limit and mode
- Drive page → Speed-limit alerts: evaluates live speed
- Speed-limit alerts → Over-limit audio: plays when enabled
- Android home widget → Android Flutter host: Android app integration