# flappedear/betterdriver architecture

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

- Interactive diagram: https://gitdiagram.com/flappedear/betterdriver
- Repository: https://github.com/flappedear/betterdriver

## Overview

BetterDriver is a cross-platform track-day coaching product: a phone records a drive and live timing, optional spoken coaching accompanies it, and the resulting session is reviewed and analysed with video. The map emphasizes this user journey plus the documented setup, track/timing, transfer, video and analysis capabilities. Edges are limited to relationships shown in the excerpts or README; several broader module interactions are therefore omitted rather than inferred.

Main entry points: [`analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/SessionAnalysis.kt`](https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/SessionAnalysis.kt) (Session Analysis), [`analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/review/SessionReview.kt`](https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/review/SessionReview.kt) (Session Review), [`app/src/main/kotlin/com/flappedear/betterdriver/recording/RecorderService.kt`](https://github.com/flappedear/betterdriver/blob/main/app/src/main/kotlin/com/flappedear/betterdriver/recording/RecorderService.kt) (Android Recorder), [`timing/src/commonMain/kotlin/com/flappedear/betterdriver/timing/track/Track.kt`](https://github.com/flappedear/betterdriver/blob/main/timing/src/commonMain/kotlin/com/flappedear/betterdriver/timing/track/Track.kt) (Track and Timing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Recording and Sensors"]
  node_setup["Equipment Setup"]
  node_recordctl["iOS Recording"]
  node_recservice["Android Recorder<br/>[RecorderService.kt]"]
  node_sessionstore[("Session Store<br/>[SessionFiles.kt]")]
end

subgraph group_live["Track and Live Coaching"]
  node_timing["Track and Timing<br/>[Track.kt]"]
  node_liveui["Track Screen"]
  node_coachsvc["Coach Service<br/>[CoachService.kt]"]
  node_cueengine["Cue Engine<br/>[CueEngine.kt]"]
end

subgraph group_review["Session Review"]
  node_review["Session Review<br/>[SessionReview.kt]"]
  node_reviewui["Lap Review UI<br/>[ReviewScreen.kt]"]
end

subgraph group_analysis["Analysis and Coaching"]
  node_analysiscore["Session Analysis<br/>[SessionAnalysis.kt]"]
  node_telemetry["Telemetry Model"]
  node_lineplan["Line Plan<br/>[LinePlan.kt]"]
  node_progress["Progress Summary<br/>[SessionProgress.kt]"]
  node_analysisui["Analysis Screens<br/>[AnalysisUi.kt]"]
  node_carui["Car Analysis<br/>[CarUi.kt]"]
  node_confidenceui["Confidence UI<br/>[ConfidenceUi.kt]"]
  node_weather["Weather Data<br/>[OpenMeteo.kt]"]
end

subgraph group_media["Video and Transfer"]
  node_video["Video Sync<br/>[GoProClient.kt]"]
  node_camera["Phone Camera<br/>[CameraService.kt]"]
  node_transfer["Session Transfer<br/>[SessionBundle.kt]"]
end

node_driver(("Driver"))

node_driver -->|"chooses equipment"| node_setup
node_driver -->|"starts drive"| node_recordctl
node_driver -->|"starts drive"| node_recservice
node_recordctl -.->|"writes session"| node_sessionstore
node_recservice -->|"stores session"| node_sessionstore
node_timing -.->|"times track"| node_liveui
node_recservice -->|"feeds live fixes"| node_timing
node_coachsvc -->|"runs cues"| node_cueengine
node_cueengine -->|"uses track data"| node_timing
node_driver -->|"reviews laps"| node_reviewui
node_reviewui -.->|"requests review"| node_review
node_review -->|"analyzes session"| node_analysiscore
node_review -.->|"reads session"| node_sessionstore
node_analysiscore -.->|"analyzes telemetry"| node_telemetry
node_analysiscore -.->|"derives plan"| node_lineplan
node_analysiscore -.->|"summarizes progress"| node_progress
node_analysisui -.->|"presents analysis"| node_analysiscore
node_carui -.->|"presents vehicle"| node_analysiscore
node_confidenceui -.->|"presents confidence"| node_analysiscore
node_camera -->|"syncs recording"| node_recservice
node_camera -.->|"indexes clips"| node_video
node_review -.->|"aligns lap clips"| node_video
node_driver -->|"transfers sessions"| node_transfer
node_weather -.->|"supplies conditions"| node_analysiscore

click node_setup "https://github.com/flappedear/betterdriver/blob/main/setup/src/commonMain/kotlin/com/flappedear/betterdriver/setup/SessionEquipment.kt"
click node_recordctl "https://github.com/flappedear/betterdriver/blob/main/ios/BetterDriver/Recording/RecordingController.swift"
click node_recservice "https://github.com/flappedear/betterdriver/blob/main/app/src/main/kotlin/com/flappedear/betterdriver/recording/RecorderService.kt"
click node_sessionstore "https://github.com/flappedear/betterdriver/blob/main/recorder/src/main/kotlin/com/flappedear/betterdriver/recorder/store/SessionFiles.kt"
click node_timing "https://github.com/flappedear/betterdriver/blob/main/timing/src/commonMain/kotlin/com/flappedear/betterdriver/timing/track/Track.kt"
click node_liveui "https://github.com/flappedear/betterdriver/tree/main/feature-track/src/main/kotlin/com/flappedear/betterdriver/feature/track"
click node_coachsvc "https://github.com/flappedear/betterdriver/blob/main/app/src/main/kotlin/com/flappedear/betterdriver/coach/CoachService.kt"
click node_cueengine "https://github.com/flappedear/betterdriver/blob/main/coach/src/commonMain/kotlin/com/flappedear/betterdriver/coach/CueEngine.kt"
click node_review "https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/review/SessionReview.kt"
click node_reviewui "https://github.com/flappedear/betterdriver/blob/main/feature-review/src/main/kotlin/com/flappedear/betterdriver/feature/review/ReviewScreen.kt"
click node_analysiscore "https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/SessionAnalysis.kt"
click node_telemetry "https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/data/TelemetrySession.kt"
click node_lineplan "https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/line/LinePlan.kt"
click node_progress "https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/summary/SessionProgress.kt"
click node_analysisui "https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/feature/analysis/AnalysisUi.kt"
click node_carui "https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/feature/analysis/CarUi.kt"
click node_confidenceui "https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/feature/analysis/ConfidenceUi.kt"
click node_video "https://github.com/flappedear/betterdriver/blob/main/videosync/src/commonMain/kotlin/com/flappedear/betterdriver/gopro/GoProClient.kt"
click node_camera "https://github.com/flappedear/betterdriver/blob/main/app/src/main/kotlin/com/flappedear/betterdriver/camera/CameraService.kt"
click node_transfer "https://github.com/flappedear/betterdriver/blob/main/transfer/src/main/kotlin/com/flappedear/betterdriver/transfer/SessionBundle.kt"
click node_weather "https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/weather/OpenMeteo.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_setup,node_recordctl,node_recservice,node_sessionstore toneBlue
class node_timing,node_liveui,node_coachsvc,node_cueengine toneAmber
class node_review,node_reviewui toneMint
class node_analysiscore,node_telemetry,node_lineplan,node_progress,node_analysisui,node_carui,node_confidenceui,node_weather toneRose
class node_video,node_camera,node_transfer,node_driver toneIndigo
```

## Components

### Recording and Sensors

- [Equipment Setup](https://github.com/flappedear/betterdriver/blob/main/setup/src/commonMain/kotlin/com/flappedear/betterdriver/setup/SessionEquipment.kt): `setup/src/commonMain/kotlin/com/flappedear/betterdriver/setup/SessionEquipment.kt`
- [iOS Recording](https://github.com/flappedear/betterdriver/blob/main/ios/BetterDriver/Recording/RecordingController.swift): `ios/BetterDriver/Recording/RecordingController.swift`
- [Android Recorder](https://github.com/flappedear/betterdriver/blob/main/app/src/main/kotlin/com/flappedear/betterdriver/recording/RecorderService.kt): `app/src/main/kotlin/com/flappedear/betterdriver/recording/RecorderService.kt`
- [Session Store](https://github.com/flappedear/betterdriver/blob/main/recorder/src/main/kotlin/com/flappedear/betterdriver/recorder/store/SessionFiles.kt): `recorder/src/main/kotlin/com/flappedear/betterdriver/recorder/store/SessionFiles.kt`

### Track and Live Coaching

- [Track and Timing](https://github.com/flappedear/betterdriver/blob/main/timing/src/commonMain/kotlin/com/flappedear/betterdriver/timing/track/Track.kt): `timing/src/commonMain/kotlin/com/flappedear/betterdriver/timing/track/Track.kt`
- [Track Screen](https://github.com/flappedear/betterdriver/tree/main/feature-track/src/main/kotlin/com/flappedear/betterdriver/feature/track): `feature-track/src/main/kotlin/com/flappedear/betterdriver/feature/track`
- [Coach Service](https://github.com/flappedear/betterdriver/blob/main/app/src/main/kotlin/com/flappedear/betterdriver/coach/CoachService.kt): `app/src/main/kotlin/com/flappedear/betterdriver/coach/CoachService.kt`
- [Cue Engine](https://github.com/flappedear/betterdriver/blob/main/coach/src/commonMain/kotlin/com/flappedear/betterdriver/coach/CueEngine.kt): `coach/src/commonMain/kotlin/com/flappedear/betterdriver/coach/CueEngine.kt`

### Session Review

- [Session Review](https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/review/SessionReview.kt): `analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/review/SessionReview.kt`
- [Lap Review UI](https://github.com/flappedear/betterdriver/blob/main/feature-review/src/main/kotlin/com/flappedear/betterdriver/feature/review/ReviewScreen.kt): `feature-review/src/main/kotlin/com/flappedear/betterdriver/feature/review/ReviewScreen.kt`

### Analysis and Coaching

- [Session Analysis](https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/SessionAnalysis.kt): `analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/SessionAnalysis.kt`
- [Telemetry Model](https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/data/TelemetrySession.kt): `analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/data/TelemetrySession.kt`
- [Line Plan](https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/line/LinePlan.kt): `analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/line/LinePlan.kt`
- [Progress Summary](https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/summary/SessionProgress.kt): `analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/summary/SessionProgress.kt`
- [Analysis Screens](https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/feature/analysis/AnalysisUi.kt): `analysis/src/commonMain/kotlin/com/flappedear/betterdriver/feature/analysis/AnalysisUi.kt`
- [Car Analysis](https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/feature/analysis/CarUi.kt): `analysis/src/commonMain/kotlin/com/flappedear/betterdriver/feature/analysis/CarUi.kt`
- [Confidence UI](https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/feature/analysis/ConfidenceUi.kt): `analysis/src/commonMain/kotlin/com/flappedear/betterdriver/feature/analysis/ConfidenceUi.kt`
- [Weather Data](https://github.com/flappedear/betterdriver/blob/main/analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/weather/OpenMeteo.kt): `analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/weather/OpenMeteo.kt`

### Video and Transfer

- [Video Sync](https://github.com/flappedear/betterdriver/blob/main/videosync/src/commonMain/kotlin/com/flappedear/betterdriver/gopro/GoProClient.kt): `videosync/src/commonMain/kotlin/com/flappedear/betterdriver/gopro/GoProClient.kt`
- [Phone Camera](https://github.com/flappedear/betterdriver/blob/main/app/src/main/kotlin/com/flappedear/betterdriver/camera/CameraService.kt): `app/src/main/kotlin/com/flappedear/betterdriver/camera/CameraService.kt`
- [Session Transfer](https://github.com/flappedear/betterdriver/blob/main/transfer/src/main/kotlin/com/flappedear/betterdriver/transfer/SessionBundle.kt): `transfer/src/main/kotlin/com/flappedear/betterdriver/transfer/SessionBundle.kt`

### Other components

- **Driver**

## Connections

- Driver → Equipment Setup: chooses equipment
- Driver → iOS Recording: starts drive
- Driver → Android Recorder: starts drive
- iOS Recording → Session Store: writes session
- Android Recorder → Session Store: stores session (evidence: `app/src/main/kotlin/com/flappedear/betterdriver/recording/RecorderService.kt`)
- Track and Timing → Track Screen: times track
- Android Recorder → Track and Timing: feeds live fixes (evidence: `app/src/main/kotlin/com/flappedear/betterdriver/recording/RecorderService.kt`)
- Coach Service → Cue Engine: runs cues (evidence: `app/src/main/kotlin/com/flappedear/betterdriver/coach/CoachService.kt`)
- Cue Engine → Track and Timing: uses track data (evidence: `coach/src/commonMain/kotlin/com/flappedear/betterdriver/coach/CueEngine.kt`)
- Driver → Lap Review UI: reviews laps
- Lap Review UI → Session Review: requests review
- Session Review → Session Analysis: analyzes session (evidence: `analysis/src/commonMain/kotlin/com/flappedear/betterdriver/analysis/review/SessionReview.kt`)
- Session Review → Session Store: reads session
- Session Analysis → Telemetry Model: analyzes telemetry
- Session Analysis → Line Plan: derives plan
- Session Analysis → Progress Summary: summarizes progress
- Analysis Screens → Session Analysis: presents analysis (evidence: `analysis/src/commonMain/kotlin/com/flappedear/betterdriver/feature/analysis/AnalysisUi.kt`)
- Car Analysis → Session Analysis: presents vehicle (evidence: `analysis/src/commonMain/kotlin/com/flappedear/betterdriver/feature/analysis/CarUi.kt`)
- Confidence UI → Session Analysis: presents confidence
- Phone Camera → Android Recorder: syncs recording (evidence: `app/src/main/kotlin/com/flappedear/betterdriver/camera/CameraService.kt`)
- Phone Camera → Video Sync: indexes clips
- Session Review → Video Sync: aligns lap clips
- Driver → Session Transfer: transfers sessions
- Weather Data → Session Analysis: supplies conditions
