muhammedshibilm/speedometer-apk

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.