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.1.0 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.1.0)

✅ Completed Features

• 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

🚧 Work in Progress Features (Seriously WIP - Dev Branch)

• Floating Window Overlay: System-level overlay window - 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
  • Android SYSTEM_ALERT_WINDOW permissions configured

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 (Dev Branch - Floating Window WIP)

• 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

Critical Issues

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

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

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