chlorinexxe/velocity

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.