258 lines
14 KiB
Markdown
258 lines
14 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
This is an Android navigation app built with Jetpack Compose that supports multiple routing providers (OSRM, Valhalla, TomTom) and includes Android Auto/Automotive OS integration. The app uses MapLibre for rendering, Androidx DataStore for local persistence, and Koin for dependency injection.
|
|
|
|
## Build Commands
|
|
|
|
```bash
|
|
# Build the app (from repository root)
|
|
./gradlew :app:assembleDebug
|
|
|
|
# Build a specific flavor
|
|
./gradlew :app:assemblePlayDebug
|
|
./gradlew :app:assembleDemoDebug
|
|
./gradlew :app:assembleFullDebug
|
|
|
|
# Run unit tests
|
|
./gradlew test
|
|
|
|
# Run tests for a specific module
|
|
./gradlew :common:data:test
|
|
./gradlew :common:car:test
|
|
|
|
# Install on device
|
|
./gradlew :app:installDebug
|
|
|
|
# Clean build
|
|
./gradlew clean
|
|
```
|
|
|
|
## Module Structure
|
|
|
|
The project uses a multi-module architecture (see `settings.gradle.kts`):
|
|
|
|
- **app/** - Main Android app with Jetpack Compose UI for phone (`com.kouros.navigation`)
|
|
- **common/data/** - Core data layer with routing logic, repositories, view models, persistence (`com.kouros.data`)
|
|
- **common/car/** - Android Auto/Automotive OS UI implementation
|
|
- **automotive/** - Placeholder for future native Automotive OS app (no Kotlin sources yet)
|
|
|
|
Dependencies flow: `app` → `common:car` → `common:data`
|
|
|
|
## Architecture
|
|
|
|
### Routing Providers (Pluggable System)
|
|
|
|
The app supports three routing engines that extend the `NavigationRepository` abstract class (`common/data/.../data/NavigationRepository.kt`):
|
|
|
|
1. **ValhallaRepository** - Valhalla routing engine (ordinal 0)
|
|
2. **OsrmRepository** - OSRM routing engine (ordinal 1)
|
|
3. **TomTomRepository** - TomTom routing engine (ordinal 2, default)
|
|
|
|
Selection is driven by `RouteEngine` enum order (see `Data.kt`). `NavigationRepository` also exposes shared HTTP helpers (`fetchUrl`, `searchPlaces`, `reverseAddress`) that use Nominatim for geocoding and `ApplicationConfig`-backed HTTP basic auth for protected endpoints.
|
|
|
|
Each provider has a corresponding mapper (`OsrmRoute`, `ValhallaRoute`, `TomTomRoute`) that converts provider-specific JSON into the universal `Route` model. The universal model is decomposed into a dedicated `data/route/` package: `Routes`, `Leg`, `Step`, `Maneuver`, `Intersection`, `Lane`, `Summary`.
|
|
|
|
**Adding a new routing provider:**
|
|
1. Create `NewProviderRepository` extending `NavigationRepository` under `common/data/src/main/java/com/kouros/navigation/data/<provider>/`
|
|
2. Implement `getRoute()` and `getTraffic()`
|
|
3. Create `NewProviderRoute.kt` with a `mapToRoute(response, builder)` function that populates a `Route.Builder`
|
|
4. Add a `RouteEngine` enum entry and provider branch in `Route.Builder.route()` (`data/Route.kt`)
|
|
5. Update `NavigationUtils.getViewModel()` (`utils/NavigationUtils.kt`) to return a `NavigationViewModel` wired to the new repository
|
|
|
|
### Data Flow
|
|
|
|
```
|
|
User action (search / select destination)
|
|
↓
|
|
NavigationViewModel.loadRoute() [LiveData / Flow]
|
|
↓
|
|
NavigationRepository.getRoute() [selected provider]
|
|
↓
|
|
*Route.mapToRoute() [convert to universal Route]
|
|
↓
|
|
RouteModel.startNavigation()
|
|
↓
|
|
RouteCalculator.findStep() [on each location update]
|
|
↓
|
|
NavigationState updated → UI observes and renders current step
|
|
```
|
|
|
|
### Key Classes
|
|
|
|
**Navigation logic** (`common/data/.../model/`):
|
|
- `RouteModel.kt` - Core navigation engine; tracks position, manages step progression, owns `NavigationState`
|
|
- `RouteCalculator.kt` - Step-finding algorithm: snaps current location to the nearest waypoint, computes leftover distance, handles snap correction and reroute thresholds
|
|
- `RouteCarModel.kt` (`common/car/.../navigation/`) - Extends RouteModel with Android Auto-specific formatting
|
|
- `NavigationViewModel.kt` - androidx ViewModel exposing route, traffic, places (Nominatim), amenities (Overpass), and fuel prices (Tankerkönig) as LiveData
|
|
- `SettingsViewModel.kt` - State holder for DataStore-backed settings (dark mode, 3D, routing engine, avoid preferences, etc.)
|
|
- `BaseStyleModel.kt` - Map style state
|
|
|
|
**Data models** (`common/data/.../data/`):
|
|
- `Route.kt` - Universal route wrapper with `Route.Builder` and provider dispatch
|
|
- `data/route/*` - Decomposed route components (`Routes`, `Leg`, `Step`, `Maneuver`, `Intersection`, `Lane`, `Summary`)
|
|
- `NavigationState.kt` - Immutable navigation state (route, flags, location, bearing, maneuver, destination)
|
|
- `Data.kt` - Shared types (`Place`, `StepData`, `SearchFilter`, `Locations`, `ValhallaLocation`) plus `object Constants` and the `RouteEngine`, `DarkMode`, `EngineType`, `ViewStyle`, `NavigationThemeColor` enums
|
|
- `ApplicationConfig.kt` - Loads `USER` / `PASSWORD` from `BuildConfig` for HTTP basic auth on protected endpoints
|
|
|
|
**Persistence** (`common/data/.../data/datastore/` and `common/data/.../repository/`):
|
|
- `DataStoreManager.kt` - Single source of truth for preference keys; exposes `Flow<T>` reads and `suspend` writes for each setting
|
|
- `SettingsRepository.kt` - Higher-level wrapper over `DataStoreManager`
|
|
|
|
**Repositories** (`common/data/.../data/`):
|
|
- `NavigationRepository.kt` - Abstract base class for routing providers; also handles Nominatim geocoding (search and reverse)
|
|
- `osrm/`, `valhalla/`, `tomtom/` - Provider implementations and JSON DTOs
|
|
- `fuel/FuelPrices.kt` - Tankerkönig fuel-price client (returns `List<Station>`)
|
|
- `overpass/` - Overpass API client for POIs and speed limits
|
|
|
|
**Android Auto / Automotive** (`common/car/`):
|
|
- `NavigationCarAppService.kt` - CarAppService entry point
|
|
- `CarSession.kt` (abstract) and concrete `NavigationSession.kt`, `ClusterSession.kt`
|
|
- `screen/NavigationScreen.kt` - Main navigation template; `NavigationType` enum drives template selection (VIEW, NAVIGATION, REROUTE, RECENT, ARRIVAL)
|
|
- `screen/SearchScreen.kt`, `RoutePreviewScreen.kt`, `PlaceListScreen.kt`, `CategoriesScreen.kt`, `CategoryScreen.kt`, `StopOverScreen.kt`, `RequestPermissionScreen.kt`
|
|
- `screen/settings/*` - Per-setting screens (RoutingSettings, NavigationSettings, DisplaySettings, DarkModeSettings, DistanceSettings, AudioSettings, CarSettings, PasswordSettings)
|
|
- `screen/observers/*` - Observer pattern that bridges LiveData to car screens. `NavigationObserverManager` orchestrates `RouteObserver`, `TrafficObserver`, `TrafficMessageObserver`, `PlaceSearchObserver`, `CategoryObserver`, `MaxSpeedObserver`, `SpeedCameraObserver`
|
|
- Supporting managers: `SurfaceRenderer.kt` (virtual display + map), `DeviceLocationManager.kt`, `CarSensorManager.kt`, `NavigationNotificationManager.kt` + `NavigationNotificationService.kt`, `TextToSpeechManager.kt`, `CustomLifecycleOwner.kt`
|
|
- `map/MapView.kt`, `map/LocationPuck.kt` - MapLibre rendering for the car surface
|
|
|
|
### External APIs
|
|
|
|
| Service | Purpose | URL |
|
|
|---------------|--------------------------|------------------------------------------------------------------------------|
|
|
| OSRM | Routing | `https://router.project-osrm.org/route/v1/driving/` |
|
|
| Valhalla | Routing | `https://kouros-online.de/valhalla/route?json=` (HTTP basic auth) |
|
|
| TomTom | Routing | `https://api.tomtom.com/routing/1/calculateRoute/` |
|
|
| TomTom | Traffic incidents | `https://api.tomtom.com/traffic/services/5/incidentDetails` |
|
|
| Nominatim | Geocoding (search/reverse) | `https://nominatim.openstreetmap.org/` |
|
|
| Overpass | POIs & speed limits | OpenStreetMap Overpass API (DEBUG builds use `https://kouros-online.de/api/interpreter`) |
|
|
| Tankerkönig | Fuel prices | `https://creativecommons.tankerkoenig.de/json/list.php?` (API key in `fuel/FuelPrices.kt`) |
|
|
|
|
In DEBUG builds, `TomTomRepository` and `FuelPrices` can be pointed at a local fixture (see `useLocal` flags) — TomTom can fall back to `R.raw.tomom_routing`, fuel falls back to a local JSON URL.
|
|
|
|
## Important Constants
|
|
|
|
Defined in `object Constants` inside `common/data/.../data/Data.kt`:
|
|
|
|
```kotlin
|
|
NEXT_STEP_THRESHOLD = 500.0 // Distance (m) to show next maneuver
|
|
DESTINATION_ARRIVAL_DISTANCE = 10.0 // Distance (m) to trigger arrival
|
|
MAXIMAL_SNAP_CORRECTION = 50.0 // Max distance (m) to snap to route
|
|
MAXIMAL_ROUTE_DEVIATION = 100.0 // Max deviation (m) before reroute
|
|
NEAREST_LOCATION_DISTANCE = 10F
|
|
SPEED_UPDATE_DISTANCE = 600F
|
|
INSTRUCTION_DISTANCE = 50
|
|
SPEED_BEARING_DEVIATION = 60
|
|
TILT = 60.0 // Map tilt in degrees during navigation
|
|
TANKER_KOENIG_DELAY = 300_000 // ms between fuel price refreshes
|
|
```
|
|
|
|
DataStore keys (see `DataStoreManager.PreferencesKeys`):
|
|
- `RoutingEngine` (Int) — `0=Valhalla`, `1=OSRM`, `2=TomTom` (default 2)
|
|
- `DarkMode` (Int), `Show3D` (Bool), `CarLocation` (Bool)
|
|
- `AvoidMotorway`, `AvoidTollway`, `AvoidFerry` (Bool)
|
|
- `LastRoute`, `RecentPlaces`, `FuelPrices`, `LastFuelPrices`
|
|
- `TomTomApiKey`, `DistanceMode`, `GuidanceAudio`, `Traffic`, `TripSuggestion`, `EngineType`, `AlternativeRoutes`
|
|
|
|
## Navigation Flow
|
|
|
|
1. **Route loading** — User searches via Nominatim → selects place → `NavigationViewModel.loadRoute()` calls the selected repository
|
|
2. **Route parsing** — Provider JSON → `*Route.mapToRoute()` populates `Route.Builder` → universal `Route` → `RouteModel.startNavigation()`
|
|
3. **Location tracking** — `FusedLocationProviderClient` updates → `RouteModel.updateLocation()`
|
|
4. **Step calculation** — `RouteCalculator.findStep()` snaps location to the nearest waypoint, returns `StepMatch`, and updates the current step index
|
|
5. **UI updates** — `NavigationState` flows out via LiveData/Compose state; phone and car UIs render the current/next step (instruction, distance, icon, lanes)
|
|
6. **Arrival** — When distance < `DESTINATION_ARRIVAL_DISTANCE`, navigation ends
|
|
|
|
## Testing Navigation
|
|
|
|
The phone app supports mock locations for testing:
|
|
|
|
- Set `useMock = true` in `MainActivity`
|
|
- Enable "Mock location app" in Android Developer Options
|
|
- Choose mode in `model/Simulation.kt` / `model/MockLocation.kt`:
|
|
- `type = 1` — Simulate movement along the entire route
|
|
- `type = 2` — Test a specific step range
|
|
- `type = 3` — Replay a GPX track file
|
|
|
|
The car module has its own `navigation/Simulation.kt` for car-side simulation.
|
|
|
|
### Unit tests
|
|
|
|
- `common/data/src/test/.../model/RouteCalculatorTest.kt`
|
|
- `common/data/src/test/.../model/RouteModelTest.kt`
|
|
- `common/data/src/test/.../model/IconMapperTest.kt`
|
|
- `common/data/src/test/.../model/OverpassTest.kt`
|
|
- `common/data/src/test/.../utils/GeoUtilsTest.kt`
|
|
- `common/car/src/test/.../screen/NavigationScreenTest.kt`
|
|
- `common/car/src/test/.../screen/observers/CategoryObserverTest.kt`, `ObserversTest.kt`
|
|
|
|
## Persistence
|
|
|
|
All app preferences are stored via Androidx **DataStore Preferences** (`navigation_settings` data store). There is no Room/ObjectBox/SQL database — the only persisted entities are settings and serialized lists (recent places, last route, last fuel prices) kept as strings.
|
|
|
|
`DataStoreManager` exposes a `Flow<T>` per setting plus a matching `suspend set*` writer. `SettingsRepository` wraps it for higher-level access. `SettingsViewModel` and `AppViewModel` consume those flows for UI state.
|
|
|
|
## Compose UI Structure
|
|
|
|
**Phone app** (`app/src/main/java/com/kouros/navigation/`):
|
|
- `ui/MainActivity.kt` - Entry point with permission handling and Navigation Compose host
|
|
- `ui/MapView.kt` - MapLibre rendering with camera state management
|
|
- `ui/SheetLayout.kt` - Bottom sheet scaffold
|
|
- `ui/PermissionScreen.kt`
|
|
- `ui/navigation/AppNavGraph.kt` - Compose navigation graph
|
|
- `ui/navigation/NavigationScreen.kt`, `NavigationSheet.kt` - Turn-by-turn UI
|
|
- `ui/search/SearchScreen.kt`, `SearchSheet.kt`
|
|
- `ui/settings/SettingsScreen.kt`, `SettingsRoute.kt`, `DisplayScreen.kt`, `NavigationScreen.kt`, `CarScreen.kt`, `Settings.kt`
|
|
- `ui/components/SettingItem.kt`, `SettingSwitch.kt`, `RadioButtonSingleSelection.kt`, `SectionTitle.kt`
|
|
- `ui/app/AppViewModel.kt`, `AppViewModelProvider.kt`
|
|
- `ui/theme/{Color,Type,Shapes,Theme}.kt`
|
|
- `model/Simulation.kt`, `model/MockLocation.kt` - Mock location for testing
|
|
- `di/appModule.kt` - Koin module
|
|
- `MainApplication.kt` - Application class
|
|
|
|
**Android Auto** uses CarAppService templates (NavigationTemplate, MessageTemplate, MapWithContentTemplate). `NavigationType` (in `screen/NavigationScreen.kt`) controls which template to render. UI state is synchronized with `NavigationViewModel` through the observers in `screen/observers/`.
|
|
|
|
## Build Flavors
|
|
|
|
`app/build.gradle.kts` defines three product flavors under the `store` dimension:
|
|
- **play** - applicationIdSuffix `.play`
|
|
- **demo** - applicationIdSuffix `.demo`
|
|
- **full** - applicationIdSuffix `.full`
|
|
|
|
Base namespace is `com.kouros.navigation`; current versionName is `0.3.0.109`. Java/Kotlin target is 21 for the app module, 11 for `common:data`. compileSdk/targetSdk = 37, minSdk = 33.
|
|
|
|
`signing.properties` (root, gitignored) provides the keystore credentials for both debug and release builds. `local.properties` provides `USER` / `PASSWORD` build config fields consumed by `ApplicationConfig`.
|
|
|
|
## Common Patterns
|
|
|
|
**Dependency injection (Koin):**
|
|
```kotlin
|
|
single { OsrmRepository() }
|
|
viewModel { NavigationViewModel(get()) }
|
|
```
|
|
|
|
**LiveData observation:**
|
|
```kotlin
|
|
viewModel.route.observe(this) { routeJson ->
|
|
routeModel.startNavigation(routeJson, context)
|
|
}
|
|
```
|
|
|
|
**Step-finding algorithm:**
|
|
`RouteCalculator` iterates the current step's waypoints, calculates distance from the current location to each, and snaps to the nearest waypoint. Snap is rejected if the closest point exceeds `MAXIMAL_SNAP_CORRECTION`; deviation greater than `MAXIMAL_ROUTE_DEVIATION` triggers a reroute.
|
|
|
|
**Settings flow:**
|
|
```kotlin
|
|
val darkMode by viewModel.darkMode.collectAsStateWithLifecycle()
|
|
```
|
|
|
|
## Known Limitations
|
|
|
|
- Valhalla route mapping is incomplete in places (search for TODO comments in `data/valhalla/ValhallaRoute.kt`)
|
|
- Rerouting logic exists but needs more testing
|
|
- Speed-limit queries via Overpass API could be optimized for performance
|
|
- TomTom and Tankerkönig clients have DEBUG-only `useLocal` shortcuts that hit fixture URLs (`http://192.168.1.37/...` and `R.raw.tomom_routing`) — these need to be off for any real-network testing
|
|
- The `automotive` module is wired into Gradle but has no Kotlin source yet
|