# swarupcreates/speedtracerproject-bikecomputer architecture

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

- Interactive diagram: https://gitdiagram.com/swarupcreates/speedtracerproject-bikecomputer
- Repository: https://github.com/swarupcreates/speedtracerproject-bikecomputer

## Overview

SpeedTracer is an ESP32-S3 cycling computer that turns GPS and sensor readings into ride metrics, navigation views, and ride logs, with local controls and a Wi-Fi web companion. In the modular firmware, App initializes and updates the services and chooses what to render. The repository also contains a large integrated firmware implementation and sensor, route, and activity modules; their detailed runtime wiring is not fully visible in the excerpts, so those links are limited to documented capabilities or marked unverified.

Main entry points: [`firmware/legacy_modular/App.cpp`](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/legacy_modular/App.cpp) (App Coordinator), [`firmware/include/services/StorageService.hpp`](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/services/StorageService.hpp) (MicroSD Storage), [`firmware/include/services/GPSService.hpp`](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/services/GPSService.hpp) (GPS and Sensor Service), [`firmware/include/services/WebService.hpp`](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/services/WebService.hpp) (Web Companion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Firmware Coordination"]
  node_app_core["App Coordinator<br/>[App.cpp]"]
end

subgraph group_telemetry["Ride Telemetry"]
  node_ride_state["Ride State<br/>[RideData.hpp]"]
  node_config["Ride Configuration<br/>[Config.hpp]"]
  node_gps["GPS and Sensor Service<br/>[GPSService.hpp]"]
  node_gps_hardware["GEPRC GPS Driver<br/>[geprc.h]"]
end

subgraph group_experience["Rider Experience"]
  node_input["Button Input<br/>[InputService.hpp]"]
  node_display["Display Service<br/>[DisplayService.hpp]"]
  node_dashboard["Dashboard Screen"]
  node_map_screen["Map Screen<br/>[MapScreen.hpp]"]
  node_splash["Splash Screen<br/>[SplashScreen.hpp]"]
  node_quick_settings["Quick Settings<br/>[quick_settings.h]"]
end

subgraph group_connectivity["Companion and Sensors"]
  node_web["Web Companion<br/>[WebService.hpp]"]
  node_ble["BLE Sensor Support<br/>[ble_sensors.h]"]
end

subgraph group_records["Navigation and Records"]
  node_nav_state["Navigation State<br/>[NavState.hpp]"]
  node_storage[("MicroSD Storage<br/>[StorageService.hpp]")]
  node_route_archive["Route Archive<br/>[route_archive.h]"]
  node_activity_archive["Activity Archive<br/>[activity_archive.h]"]
  node_fit_export["FIT Activity Export<br/>[activity_fit.h]"]
end

node_rider(("Cyclist"))
node_phone(("Phone Browser"))
node_gps_receiver["GPS Receiver"]
node_ble_sensors["BLE Sensors"]

node_rider -->|"operates"| node_app_core
node_app_core -->|"initializes"| node_display
node_app_core -->|"updates"| node_input
node_app_core -->|"updates"| node_gps
node_app_core -->|"updates"| node_web
node_app_core -->|"loads route"| node_storage
node_app_core -->|"renders"| node_splash
node_app_core -->|"renders"| node_dashboard
node_app_core -->|"renders"| node_map_screen
node_app_core -->|"updates"| node_ride_state
node_app_core -->|"loads"| node_config
node_gps -->|"uses"| node_gps_hardware
node_gps_receiver -.->|"provides fixes"| node_gps
node_ble_sensors -.->|"provides telemetry"| node_ble
node_phone -->|"controls"| node_web
node_web -->|"sets destination"| node_nav_state
node_web -->|"uses"| node_storage
node_web -->|"uses"| node_gps
node_gps -.->|"logs ride"| node_storage
node_storage -->|"loads route into"| node_nav_state
node_dashboard -->|"draws on"| node_display
node_dashboard -->|"reads"| node_gps
node_map_screen -->|"draws on"| node_display
node_map_screen -->|"reads"| node_nav_state
node_rider -.->|"adjusts"| node_quick_settings
node_quick_settings -.->|"manages"| node_ble
node_storage -.->|"stores routes"| node_route_archive
node_storage -.->|"archives rides"| node_activity_archive
node_activity_archive -.->|"exports activity"| node_fit_export

click node_app_core "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/legacy_modular/App.cpp"
click node_ride_state "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/models/RideData.hpp"
click node_nav_state "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/models/NavState.hpp"
click node_config "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/models/Config.hpp"
click node_gps "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/services/GPSService.hpp"
click node_gps_hardware "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/Drivers/geprc.h"
click node_input "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/services/InputService.hpp"
click node_display "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/services/DisplayService.hpp"
click node_dashboard "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/ui/DashboardScreen.hpp"
click node_map_screen "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/ui/MapScreen.hpp"
click node_splash "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/ui/SplashScreen.hpp"
click node_web "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/services/WebService.hpp"
click node_ble "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/src/ble_sensors.h"
click node_storage "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/services/StorageService.hpp"
click node_route_archive "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/src/route_archive.h"
click node_activity_archive "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/src/activity_archive.h"
click node_fit_export "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/src/activity_fit.h"
click node_quick_settings "https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/src/quick_settings.h"

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_core,node_phone toneBlue
class node_ride_state,node_config,node_gps,node_gps_hardware toneAmber
class node_input,node_display,node_dashboard,node_map_screen,node_splash,node_quick_settings toneMint
class node_web,node_ble toneRose
class node_nav_state,node_storage,node_route_archive,node_activity_archive,node_fit_export,node_rider,node_gps_receiver,node_ble_sensors toneIndigo
```

## Components

### Firmware Coordination

- [App Coordinator](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/legacy_modular/App.cpp): `firmware/legacy_modular/App.cpp`

### Ride Telemetry

- [Ride State](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/models/RideData.hpp): `firmware/include/models/RideData.hpp`
- [Ride Configuration](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/models/Config.hpp): `firmware/include/models/Config.hpp`
- [GPS and Sensor Service](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/services/GPSService.hpp): `firmware/include/services/GPSService.hpp`
- [GEPRC GPS Driver](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/Drivers/geprc.h): `firmware/include/Drivers/geprc.h`

### Rider Experience

- [Button Input](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/services/InputService.hpp): `firmware/include/services/InputService.hpp`
- [Display Service](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/services/DisplayService.hpp): `firmware/include/services/DisplayService.hpp`
- [Dashboard Screen](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/ui/DashboardScreen.hpp): `firmware/include/ui/DashboardScreen.hpp`
- [Map Screen](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/ui/MapScreen.hpp): `firmware/include/ui/MapScreen.hpp`
- [Splash Screen](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/ui/SplashScreen.hpp): `firmware/include/ui/SplashScreen.hpp`
- [Quick Settings](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/src/quick_settings.h): `firmware/src/quick_settings.h`

### Companion and Sensors

- [Web Companion](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/services/WebService.hpp): `firmware/include/services/WebService.hpp`
- [BLE Sensor Support](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/src/ble_sensors.h): `firmware/src/ble_sensors.h`

### Navigation and Records

- [Navigation State](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/models/NavState.hpp): `firmware/include/models/NavState.hpp`
- [MicroSD Storage](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/include/services/StorageService.hpp): `firmware/include/services/StorageService.hpp`
- [Route Archive](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/src/route_archive.h): `firmware/src/route_archive.h`
- [Activity Archive](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/src/activity_archive.h): `firmware/src/activity_archive.h`
- [FIT Activity Export](https://github.com/swarupcreates/speedtracerproject-bikecomputer/blob/main/firmware/src/activity_fit.h): `firmware/src/activity_fit.h`

### Other components

- **Cyclist**
- **Phone Browser**
- **GPS Receiver**
- **BLE Sensors**

## Connections

- Cyclist → App Coordinator: operates (evidence: `firmware/legacy_modular/App.cpp`)
- App Coordinator → Display Service: initializes (evidence: `firmware/legacy_modular/App.cpp`)
- App Coordinator → Button Input: updates (evidence: `firmware/legacy_modular/App.cpp`)
- App Coordinator → GPS and Sensor Service: updates (evidence: `firmware/legacy_modular/App.cpp`)
- App Coordinator → Web Companion: updates (evidence: `firmware/legacy_modular/App.cpp`)
- App Coordinator → MicroSD Storage: loads route (evidence: `firmware/legacy_modular/App.cpp`)
- App Coordinator → Splash Screen: renders (evidence: `firmware/legacy_modular/App.cpp`)
- App Coordinator → Dashboard Screen: renders (evidence: `firmware/legacy_modular/App.cpp`)
- App Coordinator → Map Screen: renders (evidence: `firmware/legacy_modular/App.cpp`)
- App Coordinator → Ride State: updates (evidence: `firmware/legacy_modular/App.cpp`)
- App Coordinator → Ride Configuration: loads (evidence: `firmware/legacy_modular/App.cpp`)
- GPS and Sensor Service → GEPRC GPS Driver: uses (evidence: `firmware/include/services/GPSService.hpp`)
- GPS Receiver → GPS and Sensor Service: provides fixes (evidence: `README.md`)
- BLE Sensors → BLE Sensor Support: provides telemetry (evidence: `README.md`)
- Phone Browser → Web Companion: controls (evidence: `README.md`)
- Web Companion → Navigation State: sets destination (evidence: `firmware/include/services/WebService.hpp`)
- Web Companion → MicroSD Storage: uses (evidence: `firmware/include/services/WebService.hpp`)
- Web Companion → GPS and Sensor Service: uses (evidence: `firmware/include/services/WebService.hpp`)
- GPS and Sensor Service → MicroSD Storage: logs ride (evidence: `firmware/include/services/GPSService.hpp`)
- MicroSD Storage → Navigation State: loads route into (evidence: `firmware/include/services/StorageService.hpp`)
- Dashboard Screen → Display Service: draws on (evidence: `firmware/include/ui/DashboardScreen.hpp`)
- Dashboard Screen → GPS and Sensor Service: reads (evidence: `firmware/include/ui/DashboardScreen.hpp`)
- Map Screen → Display Service: draws on (evidence: `firmware/include/ui/MapScreen.hpp`)
- Map Screen → Navigation State: reads (evidence: `firmware/include/ui/MapScreen.hpp`)
- Cyclist → Quick Settings: adjusts (evidence: `README.md`)
- Quick Settings → BLE Sensor Support: manages (evidence: `README.md`)
- MicroSD Storage → Route Archive: stores routes (evidence: `README.md`)
- MicroSD Storage → Activity Archive: archives rides (evidence: `README.md`)
- Activity Archive → FIT Activity Export: exports activity (evidence: `README.md`)
