gps-speedo/.planning/codebase/ARCHITECTURE.md

Architecture

Analysis Date: 2026-02-09

Pattern Overview

Overall: Layered Service Pattern with Reactive Data Flow

Key Characteristics:

• Singleton Service Layer - Centralized GPS data management via GpsDataManager
• Reactive Streams - Broadcast streams for reactive UI updates across main app and overlay
• Direct Communication - Main app and floating window communicate via FlutterOverlayWindow.shareData()
• Stateful Widget Hierarchy - Two independent stateful widgets (SpeedometerScreen and OverlaySpeedometer) consuming shared GPS data
• Widget-to-Widget Data Push - Main app explicitly pushes formatted data to overlay instead of shared state management

Layers

GPS Hardware Layer:

• Purpose: Acquire raw GPS data from device sensors
• Location: lib/gps_service.dart
• Contains: GPS permission handling, position stream creation, heading calculations
• Depends on: geolocator, permission_handler packages
• Used by: GpsDataManager

GPS Data Management Layer:

• Purpose: Process raw GPS data, validate signals, manage stale data timeouts, broadcast processed data
• Location: lib/services/gps_data_manager.dart
• Contains: GpsDataManager singleton, ProcessedGpsData model, stream subscription and timing logic
• Depends on: GpsService, SpeedUnit
• Used by: SpeedometerScreen and OverlaySpeedometer

UI State & Rendering Layer:

• Purpose: Consume GPS data, manage theme/unit selection, render main app and overlay screens
• Location: lib/main.dart
• Contains: SpeedometerScreen (main app widget), OverlaySpeedometer (overlay widget), layout builders, gesture handlers
• Depends on: GpsDataManager, ColorThemes, SpeedUnit, WakelockPlus, FlutterOverlayWindow, BgLauncher
• Used by: Flutter framework

Configuration/Utilities Layer:

• Purpose: Provide constants and helper functions for speed units, color themes
• Location: lib/speed_units.dart, lib/color_themes.dart
• Contains: SpeedUnit enum, ColorTheme classes, theme collection
• Depends on: Flutter Material Design
• Used by: All UI and data layers

Data Flow

GPS Data Collection & Broadcasting:

1. main.dart calls GpsDataManager.instance.initialize() on app startup
2. GpsDataManager requests permissions via GpsService.requestPermissions()
3. GpsDataManager calls Geolocator.getCurrentPosition() with 20s timeout for initial fix
4. Once initial position obtained, GpsDataManager subscribes to GpsService.positionStream() with 2s update timeout
5. Raw Position updates trigger GpsDataManager._onPositionUpdate()
6. GpsDataManager validates speed/heading, formats display strings, creates ProcessedGpsData
7. GpsDataManager broadcasts via _dataController.add(newData) (broadcast stream)
8. Both SpeedometerScreen and OverlaySpeedometer receive updates via stream subscriptions

Main App Display Update:

1. SpeedometerScreen._onGpsDataUpdate() receives ProcessedGpsData from stream
2. Updates local state: _currentGpsData, _currentUnit, _currentThemeIndex
3. Rebuilds UI with converted speed value and formatted heading
4. If overlay is active, calls _pushDataToOverlay() to sync overlay display

Overlay Activation & Communication:

1. User taps compass area of main app
2. _showFloatingWindow() executes: prepares display data, calls FlutterOverlayWindow.shareData(), launches overlay
3. FlutterOverlayWindow.showOverlay() creates new process running OverlaySpeedometer
4. Overlay's _listenToMainAppMessages() sets up listener for overlayListener
5. Main app pushes updates via periodic _pushDataToOverlay() calls when overlay active
6. Overlay applies updates to state and rebuilds display

Background Persistence:

1. App detects background transition via didChangeAppLifecycleState()
2. Enables wake lock via WakelockPlus.enable()
3. If overlay active, starts heartbeat timer every 5 seconds
4. Heartbeat calls _pushDataToOverlay() to maintain communication with overlay process
5. On resume, disables heartbeat

State Management:

• No centralized Provider - App uses direct state via setState() in main screen
• No local persistence - GPS data is ephemeral (speed, heading, validity flags)
• Settings stored in SharedPreferences - Would be implemented here if settings persistence added
• Overlay state isolated - Overlay maintains its own independent state, receives push updates from main app

Key Abstractions

ProcessedGpsData (Model):

• Purpose: Represents validated, formatted GPS information
• Examples: lib/services/gps_data_manager.dart (lines 6-40)
• Pattern: Immutable data class with copyWith() constructor for updates
• Contains: speed (m/s), heading (degrees), display strings, validity flags

GpsDataManager (Singleton Service):

• Purpose: Centralized GPS lifecycle and data processing
• Examples: lib/services/gps_data_manager.dart (lines 42-263)
• Pattern: Singleton (_instance ??= GpsDataManager._internal()) with public stream and synchronous getter
• Manages: Permission handling, GPS subscription, stale data timeouts, format conversion

SpeedUnit (Configuration Enum):

• Purpose: Speed unit definitions with conversion logic
• Examples: lib/speed_units.dart (lines 1-20)
• Pattern: Enum with associated data (label, multiplier) and methods (convert(), next)
• Values: kmh (1.0x), mph (0.621371x), knots (0.539957x) all convert from m/s via 3.6 multiplier

ColorTheme (Configuration):

• Purpose: Immutable theme definition for UI colors
• Examples: lib/color_themes.dart (lines 3-19)
• Pattern: Immutable data class with predefined theme collection
• Used by: Both main app and overlay for consistent visual styling

OverlayListener Pattern:

• Purpose: Async message passing from main app to overlay process
• Method: FlutterOverlayWindow.overlayListener.listen() (broadcast stream from plugin)
• Data format: Maps with action key and payload (speed, heading, theme index, etc.)

Entry Points

Main App Entry:

• Location: lib/main.dart (lines 22-24)
• Triggers: flutter run or app launch
• Responsibilities: Create SpeedometerApp, initialize MaterialApp theme, set home to SpeedometerScreen

Overlay Entry:

• Location: lib/main.dart (lines 27-34: overlayMain())
• Triggers: FlutterOverlayWindow.showOverlay() with overlay file parameter
• Responsibilities: Create isolated MaterialApp, set home to OverlaySpeedometer, no theme inheritance from main app
• Annotation: @pragma("vm:entry-point") required for Flutter to recognize as valid entry point

Speedometer Screen (Main):

• Location: lib/main.dart (lines 56-837: SpeedometerScreen, _SpeedometerScreenState)
• Triggers: Set as home widget in MaterialApp
• Responsibilities: Initialize GPS manager, subscribe to data stream, render portrait/landscape layouts, handle overlay lifecycle, manage background persistence

Overlay Speedometer (Floating Window):

• Location: lib/main.dart (lines 839-1075: OverlaySpeedometer, _OverlaySpeedometerState)
• Triggers: Launched via FlutterOverlayWindow.showOverlay()
• Responsibilities: Listen for main app updates, render speed/heading display, handle close and long-press gestures, send close signal to main app

Error Handling

Strategy: Graceful degradation with user-visible status

Patterns:

• GPS Service Disabled: Set display text to "GPS OFF", mark validity flags false, continue app without crash
• Permissions Denied: Set display to "NO PERM", mark validity flags false, allow user to retry via OS settings prompt
• GPS Timeout: ProcessedGpsData copied with isSpeedValid=false, display text set to "--", heading may remain valid if recently received
• Stale Data: Timer-based: after 4 seconds without update, set speed to "--" but keep heading if valid
• Overlay Errors: Wrapped in try-catch in _showFloatingWindow() and _closeFloatingWindow(), silent failures prevent main app crash
• Stream Errors: Caught in listener error handler, sets _errorMessage for display, allows user to see issue

Cross-Cutting Concerns

Logging:

• Direct print() statements with emoji prefix codes for identification
• Debug-only printing via customDebugPrint() which checks kDebugMode
• Format: [Component] emoji Descriptive message
• Examples: [GpsDataManager] 📡 Raw GPS update:, [Main] ❌ GPS stream error callback:

Validation:

• Speed validation: position.speed.isFinite && position.speed >= 0
• Heading validation: position.heading.isFinite && position.heading >= 0 && position.heading < 360
• Invalid data triggers fallback: speed becomes 0.0, heading keeps last valid value
• Display text fallback: "--" used for invalid/stale speed data

Permissions:

• Requested via Permission.locationWhenInUse.request() from permission_handler
• Overlay overlay permissions checked via FlutterOverlayWindow.isPermissionGranted()
• No permission flow UI; user must grant in Android system settings

Background Lifecycle:

• Wake lock enabled on init via WakelockPlus.enable()
• Lifecycle observer via WidgetsBinding.instance.addObserver(this)
• Background heartbeat timer prevents process hibernation when overlay active
• Multiple timer cleanup in dispose to prevent memory leaks

Overlay Synchronization:

• Size calculated in main app: (physicalSize.width * 0.45).round() for width, width * 0.6 for height
• Size sent to overlay via shareData() on creation
• Theme index and unit index sent on every update
• Speed value re-converted for overlay to use (overlay doesn't have access to _currentUnit)

---

Architecture analysis: 2026-02-09