gps-speedo/CLAUDE.md

GPS Speedometer - Claude Code Project Memory

Project Overview

A customizable Flutter GPS speedometer app targeting Android devices, emphasizing modularity and user customization.

Current Status: v2.3.0-dev Complete 

GPS speedometer with floating window overlay functionality and optimized visual design.

Architecture Implemented

• State Management: Provider pattern
• Structure: Modular widgets, providers, screens separation
• Persistence: SharedPreferences for settings
• GPS Service: Geolocator with permission handling
• UI Patterns: Consumer widgets, responsive design

Core Features Completed

•  Real-time GPS speed tracking with accuracy monitoring
•  Customizable speed units (km/h � mph) with persistent storage
•  Dual display styles: Digital speedometer + Analog gauge
•  Dark/Light theme support with system integration
•  Optional metrics panel: coordinates, distance, trip time, accuracy
•  Trip reset functionality and comprehensive error handling
•  Portrait orientation lock for mobile-first experience
•  Android permissions configuration (FINE_LOCATION, COARSE_LOCATION)

Technical Stack

Dependencies: geolocator, permission_handler, provider, shared_preferences, flutter_material_color_picker, flutter_overlay_window
Platforms: Android (primary), iOS support included but untested
Architecture: Provider + Consumer pattern for reactive state management
Permissions: Location services + SYSTEM_ALERT_WINDOW for overlay functionality

Recent Updates (v2.3.0-dev)

✅ GPS Manager Architecture (Feature Branch - Functional)

• GpsDataManager Service: Centralized singleton for all GPS data processing
• Clean Data Flow: GPS Hardware → GpsDataManager → Main App → Overlay messaging
• Separate GPS Timeouts: 20s initial fix, 2s ongoing updates for indoor/outdoor use
• Haptic Feedback: Added to all main UI interactions (theme, unit, navigation)
• Code Cleanup: Reduced verbose logging, removed unused debug variables
• Stream Architecture: Broadcast streams for reactive GPS data updates
• Background Survival: Manager integrates with existing wake locks and heartbeat

Previous Updates (v2.1.0)

✅ Completed Features (Master Branch - Stable)

• Split Decimal Display: Main speed prominent with smaller, faded decimal fraction for better readability
• Optimized Content Sizing: Maximized readability with improved responsive layout and flex ratios
• Basic Floating Window: Simple overlay with "GPS SPEEDO" text and close button (stable implementation)
• Navigation Icon Trigger: Tap compass/navigation area to launch floating window overlay
• Multiple Close Options: Overlay close button and long-press navigation area for easy dismissal
• Android System Integration: SYSTEM_ALERT_WINDOW permissions and foreground service configuration

🚧 Work in Progress Features (dev/floating-window-wip Branch - Seriously Buggy)

• Advanced Floating Window Overlay: System-level overlay with live GPS data - basic functionality works but seriously buggy
  • GPS data synchronization implemented but unreliable
  • Theme/unit sync between main app and overlay works partially
  • Proportional sizing and positioning needs major refinement
  • Close button functionality works but overlay behavior inconsistent
  • Performance may impact main app, needs optimization

Previous Updates (v1.1)

• Portrait/Landscape Support: Automatic orientation detection implemented
• Interactive Gauge: Click gauge face to switch digital/analog modes
• Extended Speed Units: Added knots support with quick selector buttons

TODO - Future Improvements

Known Issues

Master Branch (v2.1.0 - Stable):

• Dependency Updates: Update packages to latest compatible versions
• Orientation Override: Fix auto-rotate to work regardless of system toggle status

Dev Branch (floating-window-wip - Seriously Buggy):

• Floating Window Reliability: Overlay behavior inconsistent across different devices and Android versions
• GPS Data Sync: Real-time GPS synchronization between main app and overlay unreliable
• Theme/Unit Sync: Setting synchronization works partially but not consistently
• Overlay Positioning: Poor positioning stability, sizing calculations need major work
• Performance: Overlay may impact main app performance, needs optimization

UI/UX Enhancements

• Background Customization: Custom background color selection
• Interface Rearrangement: User-defined layout customization
• Settings Menu Refurbishment: More intuitive interactions and better UX

Technical Improvements

• Font Embedding: Consider custom fonts for better typography
• Feature Removal: Identify and remove unused/redundant functionalities
• Code Cleanup: Refactor deprecated warnings, optimize performance

Design Philosophy

• Preserve modularity for easy future extensions
• Prioritize user customization options
• Maintain clean, extensible architecture
• Focus on mobile-first, gesture-friendly interactions

Development Notes

• Testing: Requires physical Android device for GPS functionality
• Build System: Standard Flutter build process, first builds take time for Android SDK setup
• Memory: Project uses automatic Claude Code memory - this file for major decisions only
• Git: Active repository at https://github.com/mikkelimatlock/gps_speedo

Branch Strategy

• master: Stable releases, ready for production APK builds
• feature/gps-manager-architecture: GPS manager architecture development (functional, ready for merge)
• dev/floating-window-wip: Legacy overlay development (deprecated)
• Tagged releases: v2.2.2 on master branch contains stable functionality

Code Patterns to Maintain

• Provider pattern for state management
• Separate widgets for reusability
• Settings persistence with SharedPreferences
• Graceful error handling for GPS/permissions
• Responsive design principles