# Codebase Structure

**Analysis Date:** 2026-02-09

## Directory Layout

```
gps_speedo/
├── lib/                                # Main Dart source code
│   ├── main.dart                       # App entry points and UI widgets
│   ├── gps_service.dart                # GPS hardware abstraction
│   ├── speed_units.dart                # Speed unit enum and conversion
│   ├── color_themes.dart               # Theme data and definitions
│   └── services/
│       └── gps_data_manager.dart       # GPS data processing singleton
├── android/                            # Android native code and config
│   └── app/src/main/
│       ├── AndroidManifest.xml         # GPS and system alert window permissions
│       └── kotlin/com/novoyuuparosk/speedo/  # Android entry point
├── fonts/                              # Custom fonts
│   └── din1451alt.ttf                  # DIN 1451 Alt display font
├── icon/                               # App launcher icon
│   └── speedo.png                      # Icon image for Android/iOS
├── pubspec.yaml                        # Flutter dependencies and project config
├── pubspec.lock                        # Dependency lock file
├── analysis_options.yaml               # Dart analyzer configuration
├── test/                               # Test files
│   └── widget_test.dart                # Widget testing scaffold
└── .dart_tool/                         # Dart/Flutter build artifacts (generated)
```

## Directory Purposes

**`lib/`:**
- Purpose: All application Dart source code
- Contains: Widgets, services, models, configuration enums
- Key files: `main.dart` is the central file containing 2 widget classes (44KB)

**`lib/services/`:**
- Purpose: Business logic services isolated from UI
- Contains: `GpsDataManager` singleton service
- Key files: `gps_data_manager.dart` (264 lines of GPS processing logic)

**`android/`:**
- Purpose: Android-specific configuration and permissions
- Contains: Manifest with GPS, overlay, and location permissions; Kotlin entry point
- Key files: `AndroidManifest.xml` defines FINE_LOCATION, COARSE_LOCATION, SYSTEM_ALERT_WINDOW, READ_PHONE_STATE

**`fonts/`:**
- Purpose: Custom font assets
- Contains: DIN 1451 Alt (single font file)
- Key files: `din1451alt.ttf` referenced in pubspec.yaml

**`icon/`:**
- Purpose: Launcher icon for Android and iOS
- Contains: Single PNG image (speedo.png)
- Key files: `speedo.png` (adaptive icon source)

## Key File Locations

**Entry Points:**

- `lib/main.dart` (lines 22-24): `void main()` - Standard Flutter app entry, runs `SpeedoApp()`
- `lib/main.dart` (lines 27-34): `void overlayMain()` - Overlay process entry marked with `@pragma("vm:entry-point")`, runs `OverlaySpeedometer`
- `android/app/src/main/AndroidManifest.xml`: Android app manifest with permissions and overlay metadata

**Configuration:**

- `pubspec.yaml`: Flutter project manifest with dependency versions (geolocator 14.0.2, flutter_overlay_window 0.5.0, etc.)
- `analysis_options.yaml`: Dart linter rules
- `android/app/src/main/AndroidManifest.xml`: GPS and system permissions

**Core Logic:**

- `lib/services/gps_data_manager.dart`: GPS data singleton, stream processing, stale data timeout (4 seconds)
- `lib/gps_service.dart`: GPS permission requests, position stream factory, heading formatting
- `lib/main.dart` (lines 56-837): `SpeedometerScreen` - Main app UI, GPS subscription, overlay lifecycle
- `lib/main.dart` (lines 839-1075): `OverlaySpeedometer` - Floating window UI, data listener

**UI & Data Models:**

- `lib/main.dart` (lines 499-548): `_buildSpeedDisplay()` - Speed display renderer with split decimal parts
- `lib/main.dart` (lines 574-703): `_buildPortraitLayout()` - Portrait screen layout with speed/heading sections
- `lib/main.dart` (lines 705-836): `_buildLandscapeLayout()` - Landscape screen layout with side-by-side sections
- `lib/color_themes.dart` (lines 21-63): `ColorThemes` static list with 4 theme variants
- `lib/speed_units.dart` (lines 1-20): `SpeedUnit` enum with km/h, mph, knots conversion factors
- `lib/services/gps_data_manager.dart` (lines 6-40): `ProcessedGpsData` immutable model class

**Testing:**

- `test/widget_test.dart`: Widget test skeleton (minimal)

## Naming Conventions

**Files:**

- Snake_case: `gps_service.dart`, `gps_data_manager.dart`, `speed_units.dart`, `color_themes.dart`, `main.dart`
- Exception: `main.dart` contains all entry points and main widgets

**Directories:**

- Lowercase: `lib/`, `services/`, `android/`, `fonts/`, `icon/`, `test/`
- Java-style package paths: `android/app/src/main/kotlin/com/novoyuuparosk/speedo/`

**Classes:**

- PascalCase: `SpeedometerScreen`, `GpsDataManager`, `ProcessedGpsData`, `ColorTheme`, `ColorThemes`, `SpeedUnit`, `GpsService`, `OverlaySpeedometer`

**Functions/Methods:**

- camelCase: `initState()`, `dispose()`, `_showFloatingWindow()`, `_onGpsDataUpdate()`, `_pushDataToOverlay()`, `_cycleTheme()`, `_cycleUnit()`
- Private prefix: Methods starting with `_` (e.g., `_initializeGpsManager()`, `_buildPortraitLayout()`)

**Variables:**

- camelCase for local/member: `_currentGpsData`, `_currentUnit`, `_currentThemeIndex`, `_isOverlayActive`, `speedText`, `displaySpeed`
- Constant ALL_CAPS: `_staleDataThreshold` (const Duration), `const directions` array

**Enums:**

- PascalCase: `SpeedUnit`, with lowercase members: `SpeedUnit.kmh`, `SpeedUnit.mph`, `SpeedUnit.knots`

## Where to Add New Code

**New Feature (e.g., Speed History Tracking):**

- Primary code: Create new file in `lib/services/speed_history_manager.dart` for business logic
- Singleton pattern: Follow `GpsDataManager` structure with stream broadcasting
- UI integration: Add stream subscription in `_SpeedometerScreenState.initState()`
- Display: Add widget in `_buildPortraitLayout()` or create separate widget method
- Tests: Add to `test/widget_test.dart`

**New UI Component/Widget:**

- Implementation: Add widget class directly in `lib/main.dart` if small (<100 lines), or create separate file
- Naming: Follow PascalCase class convention, e.g., `SpeedHistoryPanel`, `MetricsDisplay`
- Props: Pass required data as constructor parameters, avoid global state
- Tests: Add widget tests in `test/widget_test.dart`

**New Configuration/Enum:**

- Speed units variant: Add new enum member to `SpeedUnit` in `lib/speed_units.dart`, add multiplier
- Color theme: Add new `ColorTheme` instance to `ColorThemes.themes` list in `lib/color_themes.dart`
- GPS behavior constants: Add to `GpsDataManager` static fields (e.g., timeout durations)

**Utilities/Helpers:**

- Shared helpers: Create `lib/utils/` directory if adding 5+ utility functions
- Single-use helpers: Keep in same file as consumer (e.g., `customDebugPrint()` in `main.dart`)
- Formatting helpers: Add to relevant domain file (`GpsService` for GPS formatting, `SpeedUnit` for speed conversion)

**New Service:**

- Location: `lib/services/new_feature_manager.dart`
- Pattern: Singleton with internal state, public stream for subscribers, async initialize method
- Lifecycle: Call `initialize()` from `SpeedometerScreen.initState()`, add stream listener
- Cleanup: Call `dispose()` in widget `dispose()` method

## Special Directories

**`lib/services/`:**
- Purpose: Business logic services (no UI widgets)
- Generated: No
- Committed: Yes
- Content: `GpsDataManager` (only service currently, designed for expansion)

**`android/`:**
- Purpose: Android native configuration and permissions
- Generated: No (manually configured, but gradle build outputs go to `build/`)
- Committed: Yes
- Key file: `AndroidManifest.xml` defines permissions needed for GPS and overlay functionality

**`build/`:**
- Purpose: Flutter/Android build artifacts
- Generated: Yes (auto-generated by `flutter build`)
- Committed: No (in .gitignore)

**`.dart_tool/`:**
- Purpose: Dart analyzer and build cache
- Generated: Yes (auto-generated by Dart tooling)
- Committed: No (in .gitignore)

**`test/`:**
- Purpose: Automated tests
- Generated: No (manually written)
- Committed: Yes
- Current state: Minimal scaffold only

---

*Structure analysis: 2026-02-09*