---
phase: 01-foundation
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - lib/services/logger.dart
  - lib/config/gps_constants.dart
  - lib/config/timing_constants.dart
  - lib/config/overlay_constants.dart
  - lib/config/speed_unit.dart
  - lib/config/color_themes.dart
  - lib/models/processed_gps_data.dart
  - lib/models/overlay_message.dart
  - lib/models/theme_model.dart
  - lib/services/gps_data_manager.dart
  - lib/main.dart
  - lib/gps_service.dart
autonomous: true

must_haves:
  truths:
    - "App compiles with flutter analyze showing zero errors"
    - "All existing functionality preserved — speed display, heading, themes, units, overlay all work identically"
    - "Logger utility exists with 4 verbosity levels (error, warn, info, debug) guarded by kDebugMode"
    - "Behavioral constants centralized in config/ with SCREAMING_SNAKE naming in abstract static classes"
    - "ProcessedGpsData model lives in models/ as separate file with immutable fields and copyWith()"
    - "OverlayMessage typed class exists with toMap()/fromMap() for overlay IPC serialization"
    - "ThemeModel exists with internal palette storage, current palette exposure, and rotate() method"
    - "SpeedUnit enum lives in config/speed_unit.dart"
    - "ColorTheme/ColorThemes classes live in config/color_themes.dart"
  artifacts:
    - path: "lib/services/logger.dart"
      provides: "Logger utility with error/warn/info/debug levels"
      contains: "class Logger"
    - path: "lib/config/gps_constants.dart"
      provides: "GPS behavioral constants"
      contains: "abstract class GpsConfig"
    - path: "lib/config/timing_constants.dart"
      provides: "Timer and interval constants"
      contains: "abstract class TimingConfig"
    - path: "lib/config/overlay_constants.dart"
      provides: "Overlay sizing and display constants"
      contains: "abstract class OverlayConfig"
    - path: "lib/config/speed_unit.dart"
      provides: "Speed unit enum with conversion"
      contains: "enum SpeedUnit"
    - path: "lib/config/color_themes.dart"
      provides: "Color theme definitions"
      contains: "class ColorTheme"
    - path: "lib/models/processed_gps_data.dart"
      provides: "Immutable GPS data model"
      contains: "class ProcessedGpsData"
    - path: "lib/models/overlay_message.dart"
      provides: "Typed overlay IPC message"
      contains: "class OverlayMessage"
    - path: "lib/models/theme_model.dart"
      provides: "Theme model with palette rotation"
      contains: "class ThemeModel"
  key_links:
    - from: "lib/services/gps_data_manager.dart"
      to: "lib/models/processed_gps_data.dart"
      via: "import and usage of ProcessedGpsData"
      pattern: "import.*models/processed_gps_data"
    - from: "lib/services/gps_data_manager.dart"
      to: "lib/config/gps_constants.dart"
      via: "import and usage of GpsConfig constants"
      pattern: "import.*config/gps_constants"
    - from: "lib/main.dart"
      to: "lib/config/speed_unit.dart"
      via: "import SpeedUnit from new location"
      pattern: "import.*config/speed_unit"
    - from: "lib/main.dart"
      to: "lib/config/color_themes.dart"
      via: "import ColorThemes from new location"
      pattern: "import.*config/color_themes"
---

<objective>
Create foundational infrastructure (directories, logger, constants) and extract all data models and config files to their proper locations in the new modular structure.

Purpose: Establishes the architectural skeleton that all subsequent Phase 1 and Phase 2 work depends on. Models, constants, and logger are the lowest-dependency pieces that everything else imports from.

Output: Logger utility, 3 constants files, 3 model files, 2 moved config files — all with updated imports across the codebase. App compiles and runs identically.
</objective>

<execution_context>
@C:\Users\SKSup\.claude/get-shit-done/workflows/execute-plan.md
@C:\Users\SKSup\.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-foundation/01-CONTEXT.md
@.planning/phases/01-foundation/01-RESEARCH.md

Source files to read before modifying:
@lib/main.dart
@lib/gps_service.dart
@lib/speed_units.dart
@lib/color_themes.dart
@lib/services/gps_data_manager.dart
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create directory structure, Logger utility, and constants files</name>
  <files>
    lib/screens/ (directory)
    lib/widgets/ (directory)
    lib/providers/ (directory)
    lib/models/ (directory)
    lib/config/ (directory)
    lib/services/logger.dart
    lib/config/gps_constants.dart
    lib/config/timing_constants.dart
    lib/config/overlay_constants.dart
  </files>
  <action>
    1. Create all six directories under lib/: screens/, widgets/, providers/, models/, config/. The services/ directory already exists.

    2. Create `lib/services/logger.dart` — a Logger utility class with 4 static methods:
       - `Logger.error(String message, [String? caller])`
       - `Logger.warn(String message, [String? caller])`
       - `Logger.info(String message, [String? caller])`
       - `Logger.debug(String message, [String? caller])`

       Implementation requirements:
       - All methods guarded by `if (kDebugMode)` from `package:flutter/foundation.dart`
       - Use `debugPrint()` (not `print()`) to avoid log truncation
       - Include ANSI color codes: red for error, yellow for warn, blue for info, gray for debug
       - Include ISO 8601 timestamp in output
       - Include caller tag in brackets when provided: `[ERROR] 2026-02-09T12:00:00 [GpsDataManager] message`
       - Reset ANSI color after each line with `\x1B[0m`

       This replaces the existing `customDebugPrint()` function in main.dart.

    3. Create `lib/config/gps_constants.dart` — extract GPS behavioral constants from gps_data_manager.dart:
       ```dart
       abstract class GpsConfig {
         static const Duration STALE_DATA_THRESHOLD = Duration(seconds: 4);
         static const Duration INITIAL_FIX_TIMEOUT = Duration(seconds: 20);
         static const Duration UPDATE_TIMEOUT = Duration(seconds: 2);
         static const double VALID_HEADING_MIN = 0.0;
         static const double VALID_HEADING_MAX = 360.0;
         static const double LOW_SPEED_THRESHOLD = 1.0;
       }
       ```
       Use SCREAMING_SNAKE naming per CONTEXT.md decisions. Include a comment at the top: `// GPS behavioral constants — SCREAMING_SNAKE per project convention`

    4. Create `lib/config/timing_constants.dart` — extract timer intervals from main.dart:
       ```dart
       abstract class TimingConfig {
         static const Duration HEARTBEAT_INTERVAL = Duration(seconds: 5);
         static const Duration OVERLAY_STATUS_CHECK_INTERVAL = Duration(milliseconds: 1000);
         static const Duration TAP_CLOSE_DELAY = Duration(milliseconds: 500);
         static const Duration LONG_PRESS_SIGNAL_DELAY = Duration(milliseconds: 50);
       }
       ```

    5. Create `lib/config/overlay_constants.dart` — extract overlay sizing constants from main.dart:
       ```dart
       abstract class OverlayConfig {
         static const double WIDTH_PERCENTAGE = 0.45;
         static const double ASPECT_RATIO = 0.6;
         static const double BACKGROUND_OPACITY = 0.85;
         static const double BORDER_OPACITY = 0.3;
         static const double FONT_SIZE_RATIO = 0.2;
         static const double UNIT_FONT_RATIO = 0.6;
         static const double ICON_SIZE_RATIO = 0.72;
         static const double HEADING_FONT_RATIO = 0.4;
         static const double DEFAULT_SCREEN_WIDTH = 400.0;
         static const double DEFAULT_OVERLAY_WIDTH = 280.0;
         static const double DEFAULT_OVERLAY_HEIGHT = 140.0;
       }
       ```

    Do NOT update any imports in main.dart or gps_data_manager.dart yet — that happens in Task 2 and Task 3.
  </action>
  <verify>
    - Run `flutter analyze` in the project root — should show zero new errors (new files are standalone, not imported yet)
    - Verify all 6 directories exist under lib/
    - Verify logger.dart, gps_constants.dart, timing_constants.dart, overlay_constants.dart all exist
  </verify>
  <done>
    Directory structure created. Logger utility exists with 4 levels guarded by kDebugMode. Three constants files exist with all behavioral magic numbers extracted using SCREAMING_SNAKE in abstract static classes.
  </done>
</task>

<task type="auto">
  <name>Task 2: Move config files and extract data models</name>
  <files>
    lib/config/speed_unit.dart
    lib/config/color_themes.dart
    lib/models/processed_gps_data.dart
    lib/models/overlay_message.dart
    lib/models/theme_model.dart
  </files>
  <action>
    1. Create `lib/config/speed_unit.dart` — copy the SpeedUnit enum from `lib/speed_units.dart` exactly as-is. Same content, new location. Do NOT delete the old file yet.

    2. Create `lib/config/color_themes.dart` — copy both ColorTheme and ColorThemes classes from `lib/color_themes.dart` exactly as-is. Same content, new location. Do NOT delete the old file yet.

    3. Create `lib/models/processed_gps_data.dart` — extract the ProcessedGpsData class from `lib/services/gps_data_manager.dart` (lines 6-40) into its own file. The class is already immutable with copyWith(). No changes to the class itself, just move it to its own file. Add the appropriate import for `package:flutter/foundation.dart` if needed (it isn't — this is a pure Dart class, no Flutter imports needed).

    4. Create `lib/models/overlay_message.dart` — a NEW typed class replacing the unvalidated Map data currently used for overlay IPC. Analyze the current overlay message maps in main.dart to determine fields:

       From `_pushDataToOverlay()` (line 403-411): action, speedText, unitText, headingText, heading, unitIndex, themeIndex
       From `_showFloatingWindow()` (line 441-450): adds overlayWidth, overlayHeight
       From overlay long press (line 1063-1064): action 'longPressClose'

       Create the class:
       ```dart
       import 'dart:convert';

       class OverlayMessage {
         final String action;
         final String? speedText;
         final String? unitText;
         final String? headingText;
         final double? heading;
         final int? unitIndex;
         final int? themeIndex;
         final double? overlayWidth;
         final double? overlayHeight;

         const OverlayMessage({
           required this.action,
           this.speedText,
           this.unitText,
           this.headingText,
           this.heading,
           this.unitIndex,
           this.themeIndex,
           this.overlayWidth,
           this.overlayHeight,
         });

         // Factory constructors for common message types
         factory OverlayMessage.updateDisplay({
           required String speedText,
           required String unitText,
           required String headingText,
           required double heading,
           required int unitIndex,
           required int themeIndex,
           double? overlayWidth,
           double? overlayHeight,
         }) {
           return OverlayMessage(
             action: 'updateDisplay',
             speedText: speedText,
             unitText: unitText,
             headingText: headingText,
             heading: heading,
             unitIndex: unitIndex,
             themeIndex: themeIndex,
             overlayWidth: overlayWidth,
             overlayHeight: overlayHeight,
           );
         }

         factory OverlayMessage.longPressClose() {
           return const OverlayMessage(action: 'longPressClose');
         }

         factory OverlayMessage.overlayClosed() {
           return const OverlayMessage(action: 'overlayClosed');
         }

         Map<String, dynamic> toMap() {
           final map = <String, dynamic>{'action': action};
           if (speedText != null) map['speedText'] = speedText;
           if (unitText != null) map['unitText'] = unitText;
           if (headingText != null) map['headingText'] = headingText;
           if (heading != null) map['heading'] = heading;
           if (unitIndex != null) map['unitIndex'] = unitIndex;
           if (themeIndex != null) map['themeIndex'] = themeIndex;
           if (overlayWidth != null) map['overlayWidth'] = overlayWidth;
           if (overlayHeight != null) map['overlayHeight'] = overlayHeight;
           return map;
         }

         factory OverlayMessage.fromMap(Map<dynamic, dynamic> map) {
           return OverlayMessage(
             action: map['action'] as String? ?? 'unknown',
             speedText: map['speedText'] as String?,
             unitText: map['unitText'] as String?,
             headingText: map['headingText'] as String?,
             heading: (map['heading'] as num?)?.toDouble(),
             unitIndex: map['unitIndex'] as int?,
             themeIndex: map['themeIndex'] as int?,
             overlayWidth: (map['overlayWidth'] as num?)?.toDouble(),
             overlayHeight: (map['overlayHeight'] as num?)?.toDouble(),
           );
         }

         OverlayMessage copyWith({...all fields...}) { ... }
       }
       ```

       Include `toMap()` and `fromMap()` because this model crosses the overlay IPC boundary via `FlutterOverlayWindow.shareData()` which requires Map data.

    5. Create `lib/models/theme_model.dart` — a new ThemeModel that wraps the existing ColorThemes:
       ```dart
       import '../config/color_themes.dart';

       class ThemeModel {
         final int _currentIndex;

         const ThemeModel({int currentIndex = 0}) : _currentIndex = currentIndex;

         // Current palette access
         ColorTheme get current => ColorThemes.getTheme(_currentIndex);
         String get currentSetName => current.name;
         int get currentIndex => _currentIndex;

         // Rotate to next theme (circular)
         ThemeModel rotate() {
           return ThemeModel(
             currentIndex: ColorThemes.getNextThemeIndex(_currentIndex),
           );
         }

         ThemeModel copyWith({int? currentIndex}) {
           return ThemeModel(
             currentIndex: currentIndex ?? _currentIndex,
           );
         }
       }
       ```

       ThemeModel delegates palette storage to ColorThemes (which holds the static list). ThemeModel only tracks current selection and provides rotation. This matches the CONTEXT.md 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." The palettes are held via delegation to ColorThemes, not duplicated.

    Do NOT update imports in main.dart or gps_data_manager.dart yet — that is Task 3.
  </action>
  <verify>
    - Run `flutter analyze` — zero new errors (new files not imported yet by existing code)
    - Verify all 5 model/config files exist in their new locations
    - Verify ProcessedGpsData in models/ matches the original in gps_data_manager.dart
  </verify>
  <done>
    SpeedUnit and ColorThemes copied to config/. ProcessedGpsData extracted to models/. OverlayMessage typed class created with toMap()/fromMap(). ThemeModel created with palette rotation.
  </done>
</task>

<task type="auto">
  <name>Task 3: Rewire all imports, replace print() with Logger, delete old files</name>
  <files>
    lib/services/gps_data_manager.dart
    lib/gps_service.dart
    lib/main.dart
    lib/speed_units.dart (delete)
    lib/color_themes.dart (delete)
  </files>
  <action>
    This is the critical wiring task. Every import must be updated in a single pass. The app must compile after this task completes.

    1. **Update `lib/services/gps_data_manager.dart`:**
       - Remove the ProcessedGpsData class definition (lines 6-40) — it now lives in models/
       - Add imports:
         ```dart
         import '../models/processed_gps_data.dart';
         import '../config/speed_unit.dart';
         import '../config/gps_constants.dart';
         import '../services/logger.dart';
         ```
       - Change import `'../speed_units.dart'` to `'../config/speed_unit.dart'`
       - Replace `_staleDataThreshold` constant with `GpsConfig.STALE_DATA_THRESHOLD`
       - Replace the Duration(seconds: 20) timeout with `GpsConfig.INITIAL_FIX_TIMEOUT`
       - Replace heading validation magic numbers (0, 360) with `GpsConfig.VALID_HEADING_MIN`, `GpsConfig.VALID_HEADING_MAX`
       - Replace ALL `print()` calls (there are ~27) with appropriate Logger calls:
         - `print('[GpsDataManager] 🚀 ...')` → `Logger.info('Starting GPS manager initialization...', 'GpsDataManager')`
         - `print('[GpsDataManager] ❌ ...')` → `Logger.error('GPS service disabled', 'GpsDataManager')`
         - `print('[GpsDataManager] ⚠️ ...')` → `Logger.warn('Already initialized, skipping...', 'GpsDataManager')`
         - `print('[GpsDataManager] 📡 ...')` → `Logger.debug('Raw GPS update: ...', 'GpsDataManager')`
         - `print('[GpsDataManager] ✅ ...')` → `Logger.info('GPS manager initialized successfully', 'GpsDataManager')`
         - Use error for failures/exceptions, warn for recoverable issues, info for lifecycle events, debug for data flow
       - Remove emoji prefixes from log messages — the Logger's color coding replaces them

    2. **Update `lib/gps_service.dart`:**
       - No import changes needed (it only imports dart:async, geolocator, permission_handler)
       - Replace heading validation magic numbers (0, 360) with GpsConfig constants:
         ```dart
         import 'config/gps_constants.dart';
         ```
         Change `heading >= 0 && heading <= 360` to `heading >= GpsConfig.VALID_HEADING_MIN && heading <= GpsConfig.VALID_HEADING_MAX`

    3. **Update `lib/main.dart`:**
       - Change `import 'speed_units.dart'` to `import 'config/speed_unit.dart'`
       - Change `import 'color_themes.dart'` to `import 'config/color_themes.dart'`
       - Add imports:
         ```dart
         import 'config/timing_constants.dart';
         import 'config/overlay_constants.dart';
         import 'models/overlay_message.dart';
         import 'services/logger.dart';
         ```
       - Remove the `customDebugPrint()` function definition (lines 16-20) — replaced by Logger
       - Replace ALL `customDebugPrint()` calls with appropriate `Logger.*()` calls:
         - Pattern: `customDebugPrint('[Main] emoji message')` → `Logger.debug('message', 'Main')` (or info/warn/error as appropriate)
         - Use Logger.error for catch blocks
         - Use Logger.warn for unexpected states
         - Use Logger.info for lifecycle transitions
         - Use Logger.debug for data flow, state changes, gesture events
       - Replace ALL remaining `print()` calls (lines 337-373 in _initializeGpsManager and _onGpsDataUpdate) with Logger calls
       - Replace magic numbers in timer durations:
         - `Duration(seconds: 5)` in heartbeat → `TimingConfig.HEARTBEAT_INTERVAL`
         - `Duration(milliseconds: 1000)` in overlay check → `TimingConfig.OVERLAY_STATUS_CHECK_INTERVAL`
         - `Duration(milliseconds: 500)` in tap close → `TimingConfig.TAP_CLOSE_DELAY`
         - `Duration(milliseconds: 50)` in long press delay → `TimingConfig.LONG_PRESS_SIGNAL_DELAY`
       - Replace magic numbers in overlay sizing:
         - `0.45` width percentage → `OverlayConfig.WIDTH_PERCENTAGE`
         - `0.6` aspect ratio → `OverlayConfig.ASPECT_RATIO`
         - `0.85` background opacity → `OverlayConfig.BACKGROUND_OPACITY`
         - `0.3` border opacity → `OverlayConfig.BORDER_OPACITY`
       - Replace overlay IPC Maps with OverlayMessage typed class:
         - In `_pushDataToOverlay()`: replace `FlutterOverlayWindow.shareData({...map...})` with `FlutterOverlayWindow.shareData(OverlayMessage.updateDisplay(...).toMap())`
         - In `_showFloatingWindow()`: replace the shareData map with `OverlayMessage.updateDisplay(...).toMap()`
         - In overlay `_listenToMainAppMessages()`: parse incoming data with `OverlayMessage.fromMap(data)`
         - In overlay long press: replace `FlutterOverlayWindow.shareData({'action': 'longPressClose'})` with `FlutterOverlayWindow.shareData(OverlayMessage.longPressClose().toMap())`
       - In `_startListeningToOverlayMessages()`: parse incoming data using OverlayMessage.fromMap() instead of raw Map access
       - In overlay constants: replace `_systemScreenWidth = 400` default with `OverlayConfig.DEFAULT_SCREEN_WIDTH`, etc.

    4. **Delete old files:**
       - Delete `lib/speed_units.dart` (moved to config/speed_unit.dart)
       - Delete `lib/color_themes.dart` (moved to config/color_themes.dart)

    **IMPORTANT:** Do not change any business logic, UI layout, gesture handling, or widget structure. Only change imports, constant references, Map→OverlayMessage conversions, and print→Logger replacements. The app must behave identically.
  </action>
  <verify>
    - Run `flutter analyze` — zero errors
    - Verify `lib/speed_units.dart` and `lib/color_themes.dart` no longer exist
    - Grep for bare `print(` in lib/ — should find zero occurrences (all replaced with Logger)
    - Grep for `customDebugPrint(` in lib/ — should find zero occurrences (all replaced with Logger)
    - Grep for `import 'speed_units.dart'` — should find zero occurrences
    - Grep for `import 'color_themes.dart'` — should find zero occurrences (only config/color_themes.dart)
    - Verify main.dart no longer contains the customDebugPrint function definition
  </verify>
  <done>
    All imports rewired to new file locations. All print()/customDebugPrint() replaced with Logger calls. All behavioral magic numbers replaced with named constants. OverlayMessage typed class used for all overlay IPC. Old speed_units.dart and color_themes.dart deleted. App compiles with zero analyzer errors.
  </done>
</task>

</tasks>

<verification>
After all 3 tasks complete:

1. `flutter analyze` returns zero errors
2. No bare `print()` calls remain in lib/ (grep confirms)
3. No `customDebugPrint()` calls remain in lib/ (grep confirms)
4. Old files deleted: lib/speed_units.dart, lib/color_themes.dart
5. Directory structure exists: lib/screens/, lib/widgets/, lib/providers/, lib/models/, lib/config/, lib/services/
6. Files exist in new locations:
   - lib/services/logger.dart
   - lib/config/gps_constants.dart, timing_constants.dart, overlay_constants.dart
   - lib/config/speed_unit.dart, color_themes.dart
   - lib/models/processed_gps_data.dart, overlay_message.dart, theme_model.dart
7. gps_data_manager.dart imports ProcessedGpsData from models/ and uses GpsConfig constants
8. main.dart imports SpeedUnit from config/ and uses TimingConfig/OverlayConfig constants
9. Overlay IPC uses OverlayMessage.toMap()/fromMap() instead of raw Maps

Requirements coverage: ORG-01 (partial — dirs created), ORG-02, ORG-03, ORG-04, ORG-05, ORG-06
</verification>

<success_criteria>
- App compiles cleanly with `flutter analyze` showing zero errors
- All 8 requirements (ORG-01 through ORG-06) addressed by this plan are satisfied
- Zero bare print() or customDebugPrint() calls remain in codebase
- All behavioral constants use named references from config/ files
- OverlayMessage typed class handles all overlay IPC serialization
</success_criteria>

<output>
After completion, create `.planning/phases/01-foundation/01-01-SUMMARY.md`
</output>