# imnoammm/kav architecture

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

- Interactive diagram: https://gitdiagram.com/imnoammm/kav
- Repository: https://github.com/imnoammm/kav

## Overview

Kav is a privacy-focused Android transit app with an optional self-hosted backend. The main rider flow runs from trip or place search through planning, route selection, and an actively guided ride; separate branches cover live transit, maps, fares, and user settings. The server provides live vehicle data, trip planning, and optional arrival predictions. The graph follows documented capabilities and sampled references; unsampled implementation details are represented only where the README supports them.

Main entry points: [`android/app/src/main/java/uk/noammm/kav/MainActivity.kt`](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/MainActivity.kt) (App shell), [`server/live.py`](https://github.com/imnoammm/kav/blob/main/server/live.py) (Server services), [`server/eta/eta.py`](https://github.com/imnoammm/kav/blob/main/server/eta/eta.py) (Arrival predictor), [`android/app/src/main/java/uk/noammm/kav/ui/Settings.kt`](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/ui/Settings.kt) (Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rider["Rider app"]
  node_app["App shell<br/>[MainActivity.kt]"]
end

subgraph group_transit["Transit data"]
  node_search["Place search<br/>[Search.kt]"]
  node_transitmodel["Transit model<br/>[Transit.kt]"]
  node_planner["Trip planner<br/>[TripPlanner.kt]"]
  node_kavplan["Kav planning API<br/>[KavPlan.kt]"]
  node_timetable[("Offline timetable<br/>[Timetable.kt]")]
  node_kavlive["Kav live API<br/>[KavLive.kt]"]
  node_journey[("Journey state<br/>[JourneyFile.kt]")]
  node_proxy["Network proxy<br/>[RiderProxy.kt]"]
end

subgraph group_features["Rider features"]
  node_lines["Lines and boards<br/>[Lines.kt]"]
  node_live["Live transit screen<br/>[LiveScreen.kt]"]
  node_guide["Ride guidance<br/>[TripService.kt]"]
  node_maps["Maps and tiles<br/>[TileMap.kt]"]
  node_payment["Rav-Pass payment<br/>[RavPass.kt]"]
  node_settings["Settings<br/>[Settings.kt]"]
end

subgraph group_backend["Kav server"]
  node_server["Server services<br/>[live.py]"]
  node_eta["Arrival predictor<br/>[eta.py]"]
  node_eta_inputs["Prediction inputs<br/>[inputs.py]"]
  node_eta_motion["Motion model<br/>[motion.py]"]
  node_eta_rail["Rail predictions<br/>[rail_inputs.py]"]
  node_otp["OTP planner<br/>[prepare.py]"]
end

node_rider(("Rider"))
node_external{{"Transit services"}}

node_rider -->|"uses"| node_app
node_app -->|"searches places"| node_search
node_app -->|"plans trips"| node_planner
node_app -->|"requests routes"| node_kavplan
node_app -->|"uses transit data"| node_transitmodel
node_planner -.->|"uses offline data"| node_timetable
node_app -->|"opens lines"| node_lines
node_app -.->|"opens live view"| node_live
node_app -->|"starts ride guidance"| node_guide
node_guide -->|"reads and clears"| node_journey
node_app -->|"saves selected trip"| node_journey
node_app -.->|"displays transit maps"| node_maps
node_app -.->|"offers fare payment"| node_payment
node_settings -->|"configures proxy"| node_proxy
node_settings -.->|"sets providers"| node_app
node_kavlive -.->|"requests live data"| node_server
node_kavplan -.->|"requests trip plans"| node_server
node_server -.->|"plans journeys"| node_otp
node_server -.->|"serves predicted arrivals"| node_eta
node_eta -->|"builds model inputs"| node_eta_inputs
node_eta -->|"uses motion model"| node_eta_motion
node_eta -->|"uses rail inputs"| node_eta_rail
node_server -.->|"fetches transport feeds"| node_external
node_search -.->|"queries chosen provider"| node_external
node_maps -.->|"loads online tiles"| node_external

click node_app "https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/MainActivity.kt"
click node_search "https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/Search.kt"
click node_transitmodel "https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/Transit.kt"
click node_planner "https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/TripPlanner.kt"
click node_kavplan "https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/KavPlan.kt"
click node_timetable "https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/Timetable.kt"
click node_kavlive "https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/KavLive.kt"
click node_lines "https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/ui/Lines.kt"
click node_live "https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/ui/LiveScreen.kt"
click node_guide "https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/TripService.kt"
click node_journey "https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/JourneyFile.kt"
click node_maps "https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/ui/TileMap.kt"
click node_payment "https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/RavPass.kt"
click node_settings "https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/ui/Settings.kt"
click node_proxy "https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/RiderProxy.kt"
click node_server "https://github.com/imnoammm/kav/blob/main/server/live.py"
click node_eta "https://github.com/imnoammm/kav/blob/main/server/eta/eta.py"
click node_eta_inputs "https://github.com/imnoammm/kav/blob/main/server/eta/inputs.py"
click node_eta_motion "https://github.com/imnoammm/kav/blob/main/server/eta/motion.py"
click node_eta_rail "https://github.com/imnoammm/kav/blob/main/server/eta/rail_inputs.py"
click node_otp "https://github.com/imnoammm/kav/blob/main/server/otp/prepare.py"

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_app toneBlue
class node_search,node_transitmodel,node_planner,node_kavplan,node_timetable,node_kavlive,node_journey,node_proxy toneAmber
class node_lines,node_live,node_guide,node_maps,node_payment,node_settings toneMint
class node_server,node_eta,node_eta_inputs,node_eta_motion,node_eta_rail,node_otp toneRose
class node_rider,node_external toneIndigo
```

## Components

### Rider app

- [App shell](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/MainActivity.kt): `android/app/src/main/java/uk/noammm/kav/MainActivity.kt`

### Transit data

- [Place search](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/Search.kt): `android/app/src/main/java/uk/noammm/kav/data/Search.kt`
- [Transit model](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/Transit.kt): `android/app/src/main/java/uk/noammm/kav/data/Transit.kt`
- [Trip planner](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/TripPlanner.kt): `android/app/src/main/java/uk/noammm/kav/data/TripPlanner.kt`
- [Kav planning API](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/KavPlan.kt): `android/app/src/main/java/uk/noammm/kav/data/KavPlan.kt`
- [Offline timetable](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/Timetable.kt): `android/app/src/main/java/uk/noammm/kav/data/Timetable.kt`
- [Kav live API](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/KavLive.kt): `android/app/src/main/java/uk/noammm/kav/data/KavLive.kt`
- [Journey state](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/JourneyFile.kt): `android/app/src/main/java/uk/noammm/kav/data/JourneyFile.kt`
- [Network proxy](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/RiderProxy.kt): `android/app/src/main/java/uk/noammm/kav/data/RiderProxy.kt`

### Rider features

- [Lines and boards](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/ui/Lines.kt): `android/app/src/main/java/uk/noammm/kav/ui/Lines.kt`
- [Live transit screen](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/ui/LiveScreen.kt): `android/app/src/main/java/uk/noammm/kav/ui/LiveScreen.kt`
- [Ride guidance](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/TripService.kt): `android/app/src/main/java/uk/noammm/kav/TripService.kt`
- [Maps and tiles](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/ui/TileMap.kt): `android/app/src/main/java/uk/noammm/kav/ui/TileMap.kt`
- [Rav-Pass payment](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/data/RavPass.kt): `android/app/src/main/java/uk/noammm/kav/data/RavPass.kt`
- [Settings](https://github.com/imnoammm/kav/blob/main/android/app/src/main/java/uk/noammm/kav/ui/Settings.kt): `android/app/src/main/java/uk/noammm/kav/ui/Settings.kt`

### Kav server

- [Server services](https://github.com/imnoammm/kav/blob/main/server/live.py): `server/live.py`
- [Arrival predictor](https://github.com/imnoammm/kav/blob/main/server/eta/eta.py): `server/eta/eta.py`
- [Prediction inputs](https://github.com/imnoammm/kav/blob/main/server/eta/inputs.py): `server/eta/inputs.py`
- [Motion model](https://github.com/imnoammm/kav/blob/main/server/eta/motion.py): `server/eta/motion.py`
- [Rail predictions](https://github.com/imnoammm/kav/blob/main/server/eta/rail_inputs.py): `server/eta/rail_inputs.py`
- [OTP planner](https://github.com/imnoammm/kav/blob/main/server/otp/prepare.py): `server/otp/prepare.py`

### Other components

- **Rider**
- **Transit services**

## Connections

- Rider → App shell: uses (evidence: `README.md`)
- App shell → Place search: searches places (evidence: `android/app/src/main/java/uk/noammm/kav/MainActivity.kt`)
- App shell → Trip planner: plans trips (evidence: `README.md`)
- App shell → Kav planning API: requests routes (evidence: `android/app/src/main/java/uk/noammm/kav/MainActivity.kt`)
- App shell → Transit model: uses transit data (evidence: `android/app/src/main/java/uk/noammm/kav/MainActivity.kt`)
- Trip planner → Offline timetable: uses offline data
- App shell → Lines and boards: opens lines (evidence: `android/app/src/main/java/uk/noammm/kav/MainActivity.kt`)
- App shell → Live transit screen: opens live view (evidence: `README.md`)
- App shell → Ride guidance: starts ride guidance (evidence: `README.md`)
- Ride guidance → Journey state: reads and clears (evidence: `android/app/src/main/java/uk/noammm/kav/TripService.kt`)
- App shell → Journey state: saves selected trip (evidence: `android/app/src/main/java/uk/noammm/kav/data/JourneyFile.kt`)
- App shell → Maps and tiles: displays transit maps (evidence: `README.md`)
- App shell → Rav-Pass payment: offers fare payment (evidence: `README.md`)
- Settings → Network proxy: configures proxy (evidence: `android/app/src/main/java/uk/noammm/kav/ui/Settings.kt`)
- Settings → App shell: sets providers (evidence: `README.md`)
- Kav live API → Server services: requests live data (evidence: `README.md`)
- Kav planning API → Server services: requests trip plans (evidence: `README.md`)
- Server services → OTP planner: plans journeys (evidence: `README.md`)
- Server services → Arrival predictor: serves predicted arrivals (evidence: `server/eta/eta.py`)
- Arrival predictor → Prediction inputs: builds model inputs (evidence: `server/eta/eta.py`)
- Arrival predictor → Motion model: uses motion model (evidence: `server/eta/eta.py`)
- Arrival predictor → Rail predictions: uses rail inputs (evidence: `server/eta/eta.py`)
- Server services → Transit services: fetches transport feeds (evidence: `README.md`)
- Place search → Transit services: queries chosen provider (evidence: `README.md`)
- Maps and tiles → Transit services: loads online tiles (evidence: `README.md`)