From 919b239c6e6cf5d25af6d5fc61cbd30962f7739e Mon Sep 17 00:00:00 2001 From: Mikkeli Matlock Date: Tue, 10 Feb 2026 10:58:15 +0900 Subject: [PATCH] docs(02): capture phase context Phase 02: Provider Migration - Implementation decisions documented - Phase boundary established --- .../02-provider-migration/02-CONTEXT.md | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 .planning/phases/02-provider-migration/02-CONTEXT.md diff --git a/.planning/phases/02-provider-migration/02-CONTEXT.md b/.planning/phases/02-provider-migration/02-CONTEXT.md new file mode 100644 index 0000000..c3a5101 --- /dev/null +++ b/.planning/phases/02-provider-migration/02-CONTEXT.md @@ -0,0 +1,70 @@ +# Phase 2: Provider Migration - Context + +**Gathered:** 2026-02-10 +**Status:** Ready for planning + + +## Phase Boundary + +Replace raw `setState()` calls with Provider pattern (ChangeNotifier/Consumer) for reactive state management. Wire all shared app state through the widget tree. Remove trip tracking feature entirely. This phase does not fix overlay reliability or GPS optimization — those are Phases 3 and 4. + + + + +## Implementation Decisions + +### State granularity +- **Separate providers per concern**: GpsDataManager (extends ChangeNotifier), SettingsProvider (theme + units combined), OverlayProvider +- No TripProvider — trip tracking (distance, trip time, trip reset) is being **removed entirely** +- Metrics panel UI removed entirely — no coordinates/accuracy/distance display +- GpsDataManager exposes only live GPS data: speed, heading, accuracy, position + +### Singleton lifecycle +- GpsDataManager **extends ChangeNotifier directly** (not wrapped by a separate provider) +- **Singleton accessor removed** — all access goes through Provider via BuildContext +- Placed at **root of widget tree** — disposed with app shutdown, not navigation +- SettingsProvider loads eagerly from **pre-initialized SharedPreferences** in main() — no splash, no flash of defaults + +### Overlay data flow +- **OverlayProvider owns all overlay messaging** — GPS data, theme, units all pushed from one place +- OverlayProvider listens to GpsDataManager stream continuously, **skips sends when overlay inactive** (if-check, not unsubscribe) +- OverlayProvider reads from SettingsProvider for theme/unit changes +- **Heartbeat/polling mechanism stripped** during migration — replaced with simple boolean flag. Phase 3 builds proper detection. + +### Migration strategy +- **Big bang migration** — all providers wired in one pass, no temporary coexistence of setState and Provider +- `setState` **preserved for purely local widget state** (animation toggles, expand/collapse) — Provider for all shared/app state +- **Granular Consumer/Selector widgets** — wrap individual widgets that depend on specific state (e.g., speed text, heading text), not broad screen sections +- Trip data, metrics panel, and all related code **removed in this phase** + +### Claude's Discretion +- Exact Consumer vs Selector usage per widget (performance optimization choices) +- Provider initialization order and MultiProvider arrangement +- How to handle permission state (whether it needs its own provider or stays procedural) +- Timer and stream subscription cleanup patterns in dispose + + + + +## Specific Ideas + +- GpsDataManager already has broadcast streams — migration path is: add ChangeNotifier mixin, call notifyListeners() from existing stream handlers, remove singleton factory +- SettingsProvider replaces the inline theme/unit cycling logic that currently lives in SpeedometerScreen +- Overlay communication simplification: strip polling timer, keep only the shareData() push mechanism with active/inactive boolean + + + + +## Deferred Ideas + +- Trip tracking / route recording — explicitly removed, could return as a future milestone feature +- Metrics panel with coordinates/accuracy — removed, could return as debug/developer mode +- Overlay reliability fixes (stale data, detection) — Phase 3 +- GPS adaptive precision — Phase 4 + + + +--- + +*Phase: 02-provider-migration* +*Context gathered: 2026-02-10*