gps-speedo/.planning/PROJECT.md

# GPS Speedometer — Restructure & Android QoL

## What this is

A restructure of the existing Flutter GPS speedometer app, splitting a 1,075-line monolithic `main.dart` into a modular architecture with proper state management, and improving Android quality of life — particularly the floating window overlay reliability, GPS response latency, and power behavior. This is not a feature expansion. It is a foundation rebuild for the same app.

## Core value

Reliable, lag-free GPS speed display that coexists politely with other Android apps.

## Requirements

### Validated

These exist and work in the current codebase.

- ✓ Real-time GPS speed tracking with accuracy monitoring — existing
- ✓ Speed units (km/h, mph, knots) with quick selector — existing
- ✓ Dual display styles: digital speedometer + analog gauge — existing
- ✓ Dark/light theme support with cycling — existing
- ✓ Optional metrics panel: coordinates, distance, trip time, accuracy — existing
- ✓ Trip reset functionality — existing
- ✓ Portrait/landscape orientation support — existing
- ✓ Android permissions handling (FINE_LOCATION, COARSE_LOCATION, SYSTEM_ALERT_WINDOW) — existing
- ✓ Floating window overlay showing speed + heading — existing (buggy)
- ✓ GpsDataManager singleton for centralized GPS processing — existing
- ✓ Haptic feedback on main UI interactions — existing
- ✓ Heading display with compass bearing — existing

### Active

Architecture:

- [ ] Modularize code into `screens/`, `widgets/`, `services/`, `providers/`, `models/` directories
- [ ] Replace raw `setState()` with proper Provider pattern (ChangeNotifier/Consumer)
- [ ] Extract overlay management from SpeedometerScreen into dedicated controller/service
- [ ] Define typed message schema for main↔overlay communication (replace unvalidated Maps)
- [ ] Replace unconditional `print()` calls with conditional debug logging (`customDebugPrint`)

Overlay reliability:

- [ ] Fix overlay data pipeline — data stops updating after running for a while
- [ ] Surface overlay errors to user (snackbar/toast instead of silent catch)
- [ ] Verify overlay creation succeeded before setting `_isOverlayActive = true`
- [ ] Remove or fix unreliable overlay status polling (1-second timer workaround)

GPS performance:

- [ ] Eliminate lag between GPS hardware fix and display update
- [ ] Speed-adaptive GPS precision: HIGH_ACCURACY above ~10 km/h, BALANCED_POWER below, with hysteresis (~8/12 km/h thresholds)
- [ ] Non-exclusive, non-locking GPS access — other apps use location normally

Power & background:

- [ ] Smart background GPS: active when overlay is visible, stopped when not
- [ ] Stop heartbeat timer when not needed (foreground + no overlay)
- [ ] Remove unnecessary wake locks — only hold when actively tracking with overlay
- [ ] Cache overlay size calculation instead of recalculating on every build

### Out of scope

- New features or UI additions — this is a restructure, not a feature release
- Dedicated settings screen — inline toggles stay as-is
- GPS interpolation or prediction between hardware fixes — display what hardware gives, instantly
- iOS testing or optimization — Android primary
- New overlay content — speed + unit + heading stays
- Comprehensive unit/integration test suite — important but separate milestone
- Dependency version upgrades — keep current versions stable

## Context

The app is a working GPS speedometer at v2.3.0-dev on the `feature/gps-manager-architecture` branch. The core problem is architectural: `main.dart` is a monolith where `SpeedometerScreen` alone is ~780 lines managing GPS subscriptions, overlay lifecycle, theme cycling, unit cycling, haptic feedback, background heartbeat, overlay status polling, and gesture handling. This makes every fix a surgical operation in a crowded file.

The `flutter_overlay_window` package has known limitations — bidirectional communication is unreliable, and the current heartbeat/polling approach is a workaround for message-based detection failures. The data pipeline going stale is likely related to timer lifecycle and stream subscription management.

Provider is already a dependency but unused — the app relies on `setState()` throughout. The restructure should wire Provider properly so state flows reactively across extracted widgets.

The GPS cooperative access constraint is important: the app uses Android's Fused Location Provider (via geolocator), which is inherently shared. But holding continuous HIGH_ACCURACY streams with wake locks is aggressive. Speed-adaptive precision reduces this to "high when actually moving, balanced when not."

SharedPreferences is mentioned in CLAUDE.md as implemented but is not actually integrated — settings reset on app restart. This is a known gap but out of scope for this restructure.

## Constraints

- **Platform**: Android primary — iOS exists but is untested and not a target
- **GPS bus**: Must be non-exclusive, non-locking — other apps access location normally
- **Power**: Mixed use — sometimes charging (car), sometimes battery (cycling, walking)
- **Overlay library**: `flutter_overlay_window 0.5.0` has known bidirectional communication issues — design around them
- **Tech stack**: Flutter/Dart, keep existing dependency set — no new major dependencies
- **Backward compatibility**: All current features must continue to work after restructure

## Key decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Speed-adaptive GPS precision (~10 km/h threshold with hysteresis) | Balances responsiveness when moving with cooperative behavior when stationary | — Pending |
| Provider pattern for state management | Already a dependency, fits Flutter idiom, enables reactive updates across extracted widgets | — Pending |
| Background GPS only when overlay visible | No reason to track location if user can't see the data | — Pending |
| Directory structure: screens/, widgets/, services/, providers/, models/ | Standard Flutter convention, separates concerns cleanly | — Pending |
| No new dependencies | Stability — restructure existing code, don't introduce new moving parts | — Pending |

---
*Last updated: 2026-02-09 after initialization*