# chlorinexxe/velocity architecture

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

- Interactive diagram: https://gitdiagram.com/chlorinexxe/velocity
- Repository: https://github.com/chlorinexxe/velocity

## Overview

#### Purpose and Runtime
Velocity is a Kotlin Android application for real-time speed, altitude/atmospheric, and compass visualization with haptic feedback and adaptive visual themes. It runs entirely in the Android app process; device sensors provide the primary live inputs. The README also states that a server-side AI API powers the core engine, but no API client or service integration path is present in the supplied tree.

#### Application Entry and Composition
`app/src/main/AndroidManifest.xml` declares the Android application and launch activity. `app/src/main/java/com/example/MainActivity.kt` is the runtime entry point, responsible for hosting the Compose-based UI and connecting application lifecycle to the main screen.

The application is built as one Android module:
- `app/build.gradle.kts`
- `build.gradle.kts`
- `settings.gradle.kts`

#### Presentation and State Boundary
The UI is centered on a screen/ViewModel split:
- `app/src/main/java/com/example/ui/MainScreen.kt`
- `app/src/main/java/com/example/ui/MainViewModel.kt`

`MainViewModel` is the state/control boundary between sensor trackers and composable rendering. `MainScreen` consumes that state to render the real-time dashboard, while specialized design components isolate each visualization:
- `app/src/main/java/com/example/ui/SpeedometerDesigns.kt`
- `app/src/main/java/com/example/ui/AtmosphereDesigns.kt`
- `app/src/main/java/com/example/ui/CompassDesigns.kt`

#### Sensor Acquisition Pipeline
Device-facing tracker components encapsulate distinct real-time signal sources:
- `app/src/main/java/com/example/sensor/SpeedTracker.kt`
- `app/src/main/java/com/example/sensor/AtmosphereTracker.kt`
- `app/src/main/java/com/example/sensor/CompassTracker.kt`

The expected control flow is Android lifecycle/activity initialization → ViewModel coordination → tracker subscription and updates → observable UI state → Compose recomposition. These trackers form the platform boundary: Android sensor, location, or atmospheric facilities should not be directly coupled to visual design code.

#### Sensory Feedback
`app/src/main/java/com/example/haptic/HapticEngine.kt` separates haptic output from the dashboard UI and sensor ingestion. The ViewModel or UI interaction layer can translate threshold crossings, motion, or user actions into device vibration effects without embedding Android haptic APIs in individual visualizations.

#### Theme and Atmospheric Rendering
Theme selection is managed independently from dashboard state:
- `app/src/main/java/com/example/theme/ThemeManager.kt`
- `app/src/main/java/com/example/ui/theme/Theme.kt`
- `app/src/main/java/com/example/ui/theme/Color.kt`

This creates a presentation boundary between semantic theme decisions and Compose styling primitives. Atmospheric data can drive `AtmosphereDesigns` and/or theme changes while speed and heading remain separately renderable.

#### Delivery Infrastructure
Gradle Kotlin DSL builds the Android artifact, with wrapper-based reproducibility under `gradle/wrapper/`. GitHub Actions provides Android CI:
- `.github/workflows/android.yml`
- `gradle/libs.versions.toml`
- `.env.example`

No backend deployment, database, or external-service implementation is represented in the tree; any AI API integration described by the README is either absent, generated elsewhere, or pending implementation.

Main entry points: [`app/src/main/java/com/example/ui/MainViewModel.kt`](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/MainViewModel.kt) (Main ViewModel), [`app/src/main/java/com/example/ui/MainScreen.kt`](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/MainScreen.kt) (Main Screen), [`app/src/main/java/com/example/MainActivity.kt`](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/MainActivity.kt) (Main Activity), [`app/src/main/java/com/example/sensor/AtmosphereTracker.kt`](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/sensor/AtmosphereTracker.kt) (Atmosphere Tracker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Android Runtime"]
  node_manifest["App Manifest<br/>Android declaration"]
  node_activity["Main Activity<br/>Android entry point<br/>[MainActivity.kt]"]
  node_viewmodel["Main ViewModel<br/>state coordinator<br/>[MainViewModel.kt]"]
  node_haptics["Haptic Engine<br/>device feedback<br/>[HapticEngine.kt]"]
end

subgraph group_sensors["Device Inputs"]
  node_platform_sensors{{"Android Sensors &amp; Location<br/>platform facilities"}}
  node_speed_tracker["Speed Tracker<br/>sensor tracker<br/>[SpeedTracker.kt]"]
  node_atmosphere_tracker["Atmosphere Tracker<br/>sensor tracker"]
  node_compass_tracker["Compass Tracker<br/>sensor tracker<br/>[CompassTracker.kt]"]
end

subgraph group_presentation["Presentation"]
  node_main_screen["Main Screen<br/>Compose screen<br/>[MainScreen.kt]"]
  node_speed_designs["Speedometer Designs<br/>Compose visualizations"]
  node_atmosphere_designs["Atmosphere Designs<br/>Compose visualizations"]
  node_compass_designs["Compass Designs<br/>Compose visualizations<br/>[CompassDesigns.kt]"]
  node_theme_manager["Theme Manager<br/>theme policy<br/>[ThemeManager.kt]"]
  node_compose_theme["Compose Theme<br/>styling primitives<br/>[Theme.kt]"]
  node_colors["Color Palette<br/>theme tokens<br/>[Color.kt]"]
end

subgraph group_delivery["Build &amp; CI"]
  node_gradle["Gradle Android Build<br/>build system<br/>[build.gradle.kts]"]
  node_ci["Android CI<br/>GitHub Actions workflow<br/>[android.yml]"]
end

node_manifest -->|"launches"| node_activity
node_activity -->|"creates / coordinates"| node_viewmodel
node_activity -->|"hosts"| node_main_screen
node_platform_sensors -->|"speed signals"| node_speed_tracker
node_platform_sensors -->|"atmospheric signals"| node_atmosphere_tracker
node_platform_sensors -->|"heading signals"| node_compass_tracker
node_viewmodel -->|"subscribes"| node_speed_tracker
node_viewmodel -->|"subscribes"| node_atmosphere_tracker
node_viewmodel -->|"subscribes"| node_compass_tracker
node_viewmodel -->|"publishes UI state"| node_main_screen
node_main_screen -->|"renders"| node_speed_designs
node_main_screen -->|"renders"| node_atmosphere_designs
node_main_screen -->|"renders"| node_compass_designs
node_atmosphere_tracker -.->|"can inform theme"| node_theme_manager
node_theme_manager -->|"selects"| node_compose_theme
node_compose_theme -->|"uses"| node_colors
node_main_screen -->|"applies"| node_compose_theme
node_viewmodel -->|"triggers feedback"| node_haptics
node_gradle -->|"packages"| node_manifest
node_ci -->|"builds"| node_gradle

click node_manifest "https://github.com/chlorinexxe/velocity/blob/main/app/src/main/AndroidManifest.xml"
click node_activity "https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/MainActivity.kt"
click node_viewmodel "https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/MainViewModel.kt"
click node_speed_tracker "https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/sensor/SpeedTracker.kt"
click node_atmosphere_tracker "https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/sensor/AtmosphereTracker.kt"
click node_compass_tracker "https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/sensor/CompassTracker.kt"
click node_main_screen "https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/MainScreen.kt"
click node_speed_designs "https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/SpeedometerDesigns.kt"
click node_atmosphere_designs "https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/AtmosphereDesigns.kt"
click node_compass_designs "https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/CompassDesigns.kt"
click node_theme_manager "https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/theme/ThemeManager.kt"
click node_compose_theme "https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/theme/Theme.kt"
click node_colors "https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/theme/Color.kt"
click node_haptics "https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/haptic/HapticEngine.kt"
click node_gradle "https://github.com/chlorinexxe/velocity/blob/main/app/build.gradle.kts"
click node_ci "https://github.com/chlorinexxe/velocity/blob/main/.github/workflows/android.yml"

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_manifest,node_activity,node_viewmodel,node_haptics toneBlue
class node_platform_sensors,node_speed_tracker,node_atmosphere_tracker,node_compass_tracker toneAmber
class node_main_screen,node_speed_designs,node_atmosphere_designs,node_compass_designs,node_theme_manager,node_compose_theme,node_colors toneMint
class node_gradle,node_ci toneRose
```

## Components

### Android Runtime

- [App Manifest](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/AndroidManifest.xml): Android declaration · Declares the application and launch activity. · `app/src/main/AndroidManifest.xml`
- [Main Activity](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/MainActivity.kt): Android entry point · Hosts Compose and connects lifecycle to the main screen. · `app/src/main/java/com/example/MainActivity.kt`
- [Main ViewModel](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/MainViewModel.kt): state coordinator · Bridges tracker updates, dashboard state, and controls. · `app/src/main/java/com/example/ui/MainViewModel.kt`
- [Haptic Engine](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/haptic/HapticEngine.kt): device feedback · Encapsulates vibration effects outside dashboard visuals. · `app/src/main/java/com/example/haptic/HapticEngine.kt`

### Device Inputs

- **Android Sensors & Location**: platform facilities · Live motion, location, and atmospheric signal sources.
- [Speed Tracker](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/sensor/SpeedTracker.kt): sensor tracker · `app/src/main/java/com/example/sensor/SpeedTracker.kt`
- [Atmosphere Tracker](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/sensor/AtmosphereTracker.kt): sensor tracker · `app/src/main/java/com/example/sensor/AtmosphereTracker.kt`
- [Compass Tracker](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/sensor/CompassTracker.kt): sensor tracker · `app/src/main/java/com/example/sensor/CompassTracker.kt`

### Presentation

- [Main Screen](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/MainScreen.kt): Compose screen · Renders the live dashboard from observable state. · `app/src/main/java/com/example/ui/MainScreen.kt`
- [Speedometer Designs](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/SpeedometerDesigns.kt): Compose visualizations · `app/src/main/java/com/example/ui/SpeedometerDesigns.kt`
- [Atmosphere Designs](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/AtmosphereDesigns.kt): Compose visualizations · `app/src/main/java/com/example/ui/AtmosphereDesigns.kt`
- [Compass Designs](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/CompassDesigns.kt): Compose visualizations · `app/src/main/java/com/example/ui/CompassDesigns.kt`
- [Theme Manager](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/theme/ThemeManager.kt): theme policy · Selects semantic themes independently of dashboard state. · `app/src/main/java/com/example/theme/ThemeManager.kt`
- [Compose Theme](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/theme/Theme.kt): styling primitives · `app/src/main/java/com/example/ui/theme/Theme.kt`
- [Color Palette](https://github.com/chlorinexxe/velocity/blob/main/app/src/main/java/com/example/ui/theme/Color.kt): theme tokens · `app/src/main/java/com/example/ui/theme/Color.kt`

### Build & CI

- [Gradle Android Build](https://github.com/chlorinexxe/velocity/blob/main/app/build.gradle.kts): build system · Builds the single Android application module. · `app/build.gradle.kts`
- [Android CI](https://github.com/chlorinexxe/velocity/blob/main/.github/workflows/android.yml): GitHub Actions workflow · `.github/workflows/android.yml`

## Connections

- App Manifest → Main Activity: launches
- Main Activity → Main ViewModel: creates / coordinates
- Main Activity → Main Screen: hosts
- Android Sensors & Location → Speed Tracker: speed signals
- Android Sensors & Location → Atmosphere Tracker: atmospheric signals
- Android Sensors & Location → Compass Tracker: heading signals
- Main ViewModel → Speed Tracker: subscribes
- Main ViewModel → Atmosphere Tracker: subscribes
- Main ViewModel → Compass Tracker: subscribes
- Main ViewModel → Main Screen: publishes UI state
- Main Screen → Speedometer Designs: renders
- Main Screen → Atmosphere Designs: renders
- Main Screen → Compass Designs: renders
- Atmosphere Tracker → Theme Manager: can inform theme
- Theme Manager → Compose Theme: selects
- Compose Theme → Color Palette: uses
- Main Screen → Compose Theme: applies
- Main ViewModel → Haptic Engine: triggers feedback
- Gradle Android Build → App Manifest: packages
- Android CI → Gradle Android Build: builds