From d41e29a1b90a2e64c4e9092d01859269cfb79509 Mon Sep 17 00:00:00 2001 From: Mikkeli Matlock Date: Mon, 9 Feb 2026 20:54:59 +0900 Subject: [PATCH] docs(01): capture phase context Phase 01: Foundation - Implementation decisions documented - Phase boundary established Co-Authored-By: Claude Opus 4.6 --- .planning/phases/01-foundation/01-CONTEXT.md | 70 ++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 .planning/phases/01-foundation/01-CONTEXT.md diff --git a/.planning/phases/01-foundation/01-CONTEXT.md b/.planning/phases/01-foundation/01-CONTEXT.md new file mode 100644 index 0000000..15e8339 --- /dev/null +++ b/.planning/phases/01-foundation/01-CONTEXT.md @@ -0,0 +1,70 @@ +# Phase 1: Foundation - Context + +**Gathered:** 2026-02-09 +**Status:** Ready for planning + + +## Phase Boundary + +Establish architectural foundation by reorganizing the monolithic Flutter app into a modular directory structure, extracting data models, centralizing behavioral constants, and replacing raw print statements with a proper logger. All existing functionality must remain identical after reorganization. + + + + +## Implementation Decisions + +### Directory conventions +- Layer-first structure directly under lib/: screens/, widgets/, providers/, services/, models/, config/ +- Flat widget structure — all widget files directly in widgets/, no subdirectories +- Overlay-specific code lives within the layer folders (overlay widgets in widgets/, overlay services in services/) rather than a dedicated overlay/ directory +- File names match class names exactly: GpsDataManager → gps_data_manager.dart + +### Model extraction +- ProcessedGpsData, OverlayMessage, and a Theme model to be extracted +- Models are immutable — all fields final, changes via copyWith() +- Theme model holds all available color palettes internally, exposes only the current palette's named colors, a "current set name" label, and a rotate() method for cycling themes +- Persistence (SharedPreferences) handled separately from the theme model itself + +### Claude's Discretion +- Whether models include formatting/serialization helpers (toMap, fromMap) based on current usage patterns +- Exact fields and structure of each model based on existing code analysis +- How theme palette rotation wraps (circular vs bounded) + +### Constants organization +- Split by domain into separate files: config/gps_constants.dart, config/ui_constants.dart, config/timing_constants.dart, etc. +- Extract behavioral constants only (timeouts, thresholds, GPS settings, speed limits) — leave UI padding/sizing as inline values +- SCREAMING_SNAKE naming convention: GPS_TIMEOUT_SECONDS, SPEED_THRESHOLD_HIGH +- Grouped into abstract classes with static members: GpsConfig.TIMEOUT_SECONDS, TimingConfig.HEARTBEAT_INTERVAL + +### Migration strategy +- Incremental migration — app must compile and run after each execution wave +- When files move, all imports updated immediately (no temporary re-exports) +- No intermediate broken states; each wave is a working checkpoint + +### Debug logging +- Semi-proper logger with 4 verbosity levels: error, warn, info, debug +- Include caller name and timestamp in log output +- Replaces all existing unconditional print statements + + + + +## Specific Ideas + +- Theme model mental model: "holds all possible colour palettes, exposing only the current set of colours (with their nametags), informative 'current set name', and a method for rotating themes" +- App must be runnable on a bench phone after each session/wave — this is a hard verification constraint +- Logger should feel like a proper utility, not just a debugPrint wrapper + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 01-foundation* +*Context gathered: 2026-02-09*