# TracPulse — Developer Guide

## Build

```bash
# Debug APK
flutter build apk --debug

# Release APK (requires signing config)
flutter build apk --release

# Analyze
flutter analyze

# Format
dart format .
```

## Project Structure

```
lib/
  main.dart                 # App entry, dark theme, routing
  main_screen.dart          # Tracking toggle + live coordinates
  permission_screen.dart    # Pre-flight permission setup
  settings_screen.dart      # Server URL, device ID, accuracy config
  status_screen.dart        # Event log (LOCATION, SYNC, ERROR, etc.)
  preferences.dart          # SharedPreferences wrapper
  bridge/
    location_bridge.dart    # Dart↔Native MethodChannel

android/app/src/main/kotlin/dev/fiatcode/tracpulse/
  MainActivity.kt           # Flutter activity
  BridgeModule.kt           # Method channel handler
  service/
    LocationTrackingService.kt  # Foreground service
  location/
    HeartbeatScheduler.kt   # AlarmManager-based heartbeat
    DistanceFilterProcessor.kt  # Haversine distance filter
    FusedLocationProvider.kt   # FusedLocationClient wrapper
  network/
    TraccarHttpClient.kt    # HTTP client for Traccar protocol
    ConnectivityReceiver.kt # Network state monitoring
  storage/
    AppDatabase.kt          # Room database singleton
    LocationDao.kt          # Location entity DAO
    EventLogDao.kt          # Event log DAO
    LocationEntity.kt       # Location Room entity
    EventLogEntity.kt       # Event log Room entity
  model/
    Location.kt             # Location data class
    EventLogEntry.kt        # Event log entry data class
```

## Architecture

- **Flutter** UI layer with dark monospace theme
- **MethodChannel** (`com.traccar.client/tracking`) bridges Dart to Kotlin
- **Foreground Service** (`LocationTrackingService`) handles location updates
- **HeartbeatScheduler** uses `AlarmManager` (not WorkManager — callbacks lost in separate process)
- **Offline buffering** via Room database when network unavailable

## Configuration Flow

1. `PermissionScreen` — guides through locationAlways + notification + battery optimization
2. `SettingsScreen` — server URL, device ID, accuracy, intervals
3. Preferences stored via `SharedPreferences` (synced to native via `updateConfig`)

## Server Request Format

```
POST https://yourserver/?id=DEVICE_ID&lat=...&lon=...&timestamp=...&is_moving=0
```

- `is_moving` = `1` when `speed > 1.0 m/s`
- Auth via Basic auth header if password configured

## Key Patterns

- **Permission flow**: WhenInUse → Always (required order for background location)
- **Battery optimization**: `PowerManager.isIgnoringBatteryOptimizations` via BridgeModule
- **Tracking config**: passed via `startTracking()` + `updateConfig()` (both required)
- **Dark theme**: `Brightness.dark` with `#0d0d0d` background, teal `#00bcd4` accent