# kurtisho/optirun-android architecture

> Architecture diagram of the GitHub repository kurtisho/optirun-android, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kurtisho/optirun-android
- Repository: https://github.com/kurtisho/optirun-android

## Overview

OptiRun is an Android running-planner app. A runner chooses a start location and weather, terrain, and distance preferences; the app then finds suitable forecast windows and a suggested loop, presenting both on a results screen. The graph preserves the separate place-search, location, weather, route, and domain-scoring stages. Connections are cited where the supplied excerpts or source index establish them; external service links are dashed because no host or network-call implementation was shown.

Main entry points: [`app/src/main/java/com/kurtis/optirun/ui/results/ResultsViewModel.kt`](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/ui/results/ResultsViewModel.kt) (Plan orchestration), [`app/src/main/java/com/kurtis/optirun/ui/results/ResultsScreen.kt`](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/ui/results/ResultsScreen.kt) (Plan presentation), [`app/src/main/java/com/kurtis/optirun/data/route/OrsApi.kt`](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/data/route/OrsApi.kt) (ORS adapter), [`app/src/main/java/com/kurtis/optirun/domain/model`](https://github.com/kurtisho/optirun-android/tree/main/app/src/main/java/com/kurtis/optirun/domain/model) (Planning data models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_activity["App entry<br/>[MainActivity.kt]"]
  node_navigation["Navigation<br/>[Navigation.kt]"]
  node_home["Run preferences<br/>[HomeScreen.kt]"]
  node_results["Plan presentation<br/>[ResultsScreen.kt]"]
  node_map["Route map<br/>[RouteMap.kt]"]
end

subgraph group_inputs["Start selection"]
  node_homevm["Place search state<br/>[HomeViewModel.kt]"]
  node_location["Current location"]
end

subgraph group_data["Data services"]
  node_places["Place lookup<br/>[PlaceRepository.kt]"]
  node_orsapi["ORS adapter<br/>[OrsApi.kt]"]
  node_routemgr["Loop generation<br/>[RouteRepository.kt]"]
  node_weatherrepo["Forecast mapping<br/>[WeatherRepo.kt]"]
  node_weatherapi["Forecast adapter<br/>[OpenMeteoApi.kt]"]
end

subgraph group_planning["Run planning"]
  node_resultsviewmodel["Plan orchestration"]
  node_windowmatcher["Weather window scoring<br/>[WindowMatcher.kt]"]
  node_terrain["Terrain matching"]
  node_elevation["Elevation calculations<br/>[ElevationMath.kt]"]
  node_models["Planning data models"]
end

node_runner(("Runner"))
node_ors{{"OpenRouteService"}}
node_meteo{{"Open-Meteo"}}

node_runner -->|"opens app"| node_activity
node_activity -.->|"starts navigation"| node_navigation
node_navigation -->|"routes to"| node_home
node_navigation -->|"routes to"| node_results
node_runner -->|"sets preferences"| node_home
node_home -->|"searches places"| node_homevm
node_homevm -->|"requests suggestions"| node_places
node_homevm -->|"requests location"| node_location
node_places -->|"geocodes query"| node_orsapi
node_orsapi -.->|"calls geocoding"| node_ors
node_resultsviewmodel -->|"gets location"| node_location
node_resultsviewmodel -->|"fetches forecast"| node_weatherrepo
node_resultsviewmodel -->|"requests loops"| node_routemgr
node_weatherrepo -->|"requests hourly data"| node_weatherapi
node_weatherapi -.->|"fetches forecast"| node_meteo
node_routemgr -->|"requests round trips"| node_orsapi
node_orsapi -.->|"requests routes"| node_ors
node_routemgr -->|"computes ascent"| node_elevation
node_resultsviewmodel -->|"scores windows"| node_windowmatcher
node_resultsviewmodel -->|"selects terrain"| node_terrain
node_resultsviewmodel -->|"supplies plan state"| node_results
node_results -->|"renders route"| node_map
node_windowmatcher -->|"uses weather and preferences"| node_models
node_terrain -->|"classifies route"| node_models
node_results -->|"displays plan data"| node_models
node_map -->|"draws route path"| node_models

click node_activity "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/MainActivity.kt"
click node_navigation "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/ui/Navigation.kt"
click node_home "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/ui/home/HomeScreen.kt"
click node_homevm "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/ui/home/HomeViewModel.kt"
click node_location "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/data/location/LocationProvider.kt"
click node_places "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/data/route/PlaceRepository.kt"
click node_orsapi "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/data/route/OrsApi.kt"
click node_routemgr "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/data/route/RouteRepository.kt"
click node_weatherrepo "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/data/weather/WeatherRepo.kt"
click node_weatherapi "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/data/weather/OpenMeteoApi.kt"
click node_resultsviewmodel "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/ui/results/ResultsViewModel.kt"
click node_windowmatcher "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/domain/usecase/WindowMatcher.kt"
click node_terrain "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/domain/usecase/TerrainClassifier.kt"
click node_elevation "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/domain/usecase/ElevationMath.kt"
click node_models "https://github.com/kurtisho/optirun-android/tree/main/app/src/main/java/com/kurtis/optirun/domain/model"
click node_results "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/ui/results/ResultsScreen.kt"
click node_map "https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/ui/results/RouteMap.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_activity,node_navigation,node_home,node_results,node_map toneBlue
class node_homevm,node_location toneAmber
class node_places,node_orsapi,node_routemgr,node_weatherrepo,node_weatherapi,node_ors toneMint
class node_resultsviewmodel,node_windowmatcher,node_terrain,node_elevation,node_models toneRose
class node_runner,node_meteo toneIndigo
```

## Components

### App experience

- [App entry](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/MainActivity.kt): `app/src/main/java/com/kurtis/optirun/MainActivity.kt`
- [Navigation](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/ui/Navigation.kt): `app/src/main/java/com/kurtis/optirun/ui/Navigation.kt`
- [Run preferences](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/ui/home/HomeScreen.kt): `app/src/main/java/com/kurtis/optirun/ui/home/HomeScreen.kt`
- [Plan presentation](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/ui/results/ResultsScreen.kt): `app/src/main/java/com/kurtis/optirun/ui/results/ResultsScreen.kt`
- [Route map](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/ui/results/RouteMap.kt): `app/src/main/java/com/kurtis/optirun/ui/results/RouteMap.kt`

### Start selection

- [Place search state](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/ui/home/HomeViewModel.kt): `app/src/main/java/com/kurtis/optirun/ui/home/HomeViewModel.kt`
- [Current location](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/data/location/LocationProvider.kt): `app/src/main/java/com/kurtis/optirun/data/location/LocationProvider.kt`

### Data services

- [Place lookup](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/data/route/PlaceRepository.kt): `app/src/main/java/com/kurtis/optirun/data/route/PlaceRepository.kt`
- [ORS adapter](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/data/route/OrsApi.kt): `app/src/main/java/com/kurtis/optirun/data/route/OrsApi.kt`
- [Loop generation](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/data/route/RouteRepository.kt): `app/src/main/java/com/kurtis/optirun/data/route/RouteRepository.kt`
- [Forecast mapping](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/data/weather/WeatherRepo.kt): `app/src/main/java/com/kurtis/optirun/data/weather/WeatherRepo.kt`
- [Forecast adapter](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/data/weather/OpenMeteoApi.kt): `app/src/main/java/com/kurtis/optirun/data/weather/OpenMeteoApi.kt`

### Run planning

- [Plan orchestration](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/ui/results/ResultsViewModel.kt): `app/src/main/java/com/kurtis/optirun/ui/results/ResultsViewModel.kt`
- [Weather window scoring](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/domain/usecase/WindowMatcher.kt): `app/src/main/java/com/kurtis/optirun/domain/usecase/WindowMatcher.kt`
- [Terrain matching](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/domain/usecase/TerrainClassifier.kt): `app/src/main/java/com/kurtis/optirun/domain/usecase/TerrainClassifier.kt`
- [Elevation calculations](https://github.com/kurtisho/optirun-android/blob/main/app/src/main/java/com/kurtis/optirun/domain/usecase/ElevationMath.kt): `app/src/main/java/com/kurtis/optirun/domain/usecase/ElevationMath.kt`
- [Planning data models](https://github.com/kurtisho/optirun-android/tree/main/app/src/main/java/com/kurtis/optirun/domain/model): `app/src/main/java/com/kurtis/optirun/domain/model`

### Other components

- **Runner**
- **OpenRouteService**
- **Open-Meteo**

## Connections

- Runner → App entry: opens app
- App entry → Navigation: starts navigation
- Navigation → Run preferences: routes to (evidence: `app/src/main/java/com/kurtis/optirun/ui/Navigation.kt`)
- Navigation → Plan presentation: routes to (evidence: `app/src/main/java/com/kurtis/optirun/ui/Navigation.kt`)
- Runner → Run preferences: sets preferences (evidence: `app/src/main/java/com/kurtis/optirun/ui/home/HomeScreen.kt`)
- Run preferences → Place search state: searches places (evidence: `app/src/main/java/com/kurtis/optirun/ui/home/HomeScreen.kt`)
- Place search state → Place lookup: requests suggestions (evidence: `app/src/main/java/com/kurtis/optirun/ui/home/HomeViewModel.kt`)
- Place search state → Current location: requests location (evidence: `app/src/main/java/com/kurtis/optirun/ui/home/HomeViewModel.kt`)
- Place lookup → ORS adapter: geocodes query (evidence: `app/src/main/java/com/kurtis/optirun/data/route/PlaceRepository.kt`)
- ORS adapter → OpenRouteService: calls geocoding
- Plan orchestration → Current location: gets location (evidence: `app/src/main/java/com/kurtis/optirun/ui/results/ResultsViewModel.kt`)
- Plan orchestration → Forecast mapping: fetches forecast (evidence: `app/src/main/java/com/kurtis/optirun/ui/results/ResultsViewModel.kt`)
- Plan orchestration → Loop generation: requests loops (evidence: `app/src/main/java/com/kurtis/optirun/ui/results/ResultsViewModel.kt`)
- Forecast mapping → Forecast adapter: requests hourly data (evidence: `app/src/main/java/com/kurtis/optirun/data/weather/WeatherRepo.kt`)
- Forecast adapter → Open-Meteo: fetches forecast
- Loop generation → ORS adapter: requests round trips (evidence: `app/src/main/java/com/kurtis/optirun/data/route/RouteRepository.kt`)
- ORS adapter → OpenRouteService: requests routes
- Loop generation → Elevation calculations: computes ascent (evidence: `app/src/main/java/com/kurtis/optirun/data/route/RouteRepository.kt`)
- Plan orchestration → Weather window scoring: scores windows (evidence: `app/src/main/java/com/kurtis/optirun/ui/results/ResultsViewModel.kt`)
- Plan orchestration → Terrain matching: selects terrain (evidence: `app/src/main/java/com/kurtis/optirun/ui/results/ResultsViewModel.kt`)
- Plan orchestration → Plan presentation: supplies plan state (evidence: `app/src/main/java/com/kurtis/optirun/ui/results/ResultsScreen.kt`)
- Plan presentation → Route map: renders route (evidence: `app/src/main/java/com/kurtis/optirun/ui/results/ResultsScreen.kt`)
- Weather window scoring → Planning data models: uses weather and preferences (evidence: `app/src/main/java/com/kurtis/optirun/domain/usecase/WindowMatcher.kt`)
- Terrain matching → Planning data models: classifies route (evidence: `app/src/main/java/com/kurtis/optirun/domain/usecase/TerrainClassifier.kt`)
- Plan presentation → Planning data models: displays plan data (evidence: `app/src/main/java/com/kurtis/optirun/ui/results/ResultsScreen.kt`)
- Route map → Planning data models: draws route path (evidence: `app/src/main/java/com/kurtis/optirun/ui/results/RouteMap.kt`)
