# lungmen-hkm/trainercraft architecture

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

- Interactive diagram: https://gitdiagram.com/lungmen-hkm/trainercraft
- Repository: https://github.com/lungmen-hkm/trainercraft

## Overview

TrainerCraft bridges BLE cycling telemetry into Minecraft Bedrock bike movement. The documented flow is sensor data into the Flutter app, speed calculation and WebSocket broadcast, then Minecraft-side speed mapping and vehicle movement. The Dart service implementations were not included in the sampled source, so their internal calls and precise message handling are represented only where the README documents the flow. Other-game adapters are a proposed extension, not an implemented subsystem in this tree.

Main entry points: [`app_bridge/lib/services/ble_service.dart`](https://github.com/lungmen-hkm/trainercraft/blob/master/app_bridge/lib/services/ble_service.dart) (BLE ingestion), [`app_bridge/lib/services/server_service.dart`](https://github.com/lungmen-hkm/trainercraft/blob/master/app_bridge/lib/services/server_service.dart) (WebSocket server), [`app_bridge/lib/main.dart`](https://github.com/lungmen-hkm/trainercraft/blob/master/app_bridge/lib/main.dart) (App entry), [`mc_addon/TrainerCraft-BP/scripts/main.js`](https://github.com/lungmen-hkm/trainercraft/blob/master/mc_addon/TrainerCraft-BP/scripts/main.js) (Speed listener and tick loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Flutter bridge"]
  node_ble["BLE ingestion<br/>[ble_service.dart]"]
  node_app_entry["App entry<br/>[main.dart]"]
  node_ws["WebSocket server"]
end

subgraph group_game["Minecraft add-on"]
  node_script["Speed listener and tick loop<br/>[main.js]"]
  node_bike["TrainerCraft bike<br/>[bike.json]"]
end

node_sensor(("BLE CSC sensor"))
node_bedrock(("Bedrock runtime"))

node_sensor -->|"sends CSC data"| node_ble
node_app_entry -->|"uses"| node_ble
node_app_entry -->|"uses"| node_ws
node_ble -->|"provides telemetry"| node_ws
node_ws -->|"broadcasts over WebSocket"| node_bedrock
node_bedrock -->|"delivers speed event"| node_script
node_script -->|"sets movement"| node_bike

click node_ble "https://github.com/lungmen-hkm/trainercraft/blob/master/app_bridge/lib/services/ble_service.dart"
click node_app_entry "https://github.com/lungmen-hkm/trainercraft/blob/master/app_bridge/lib/main.dart"
click node_ws "https://github.com/lungmen-hkm/trainercraft/blob/master/app_bridge/lib/services/server_service.dart"
click node_script "https://github.com/lungmen-hkm/trainercraft/blob/master/mc_addon/TrainerCraft-BP/scripts/main.js"
click node_bike "https://github.com/lungmen-hkm/trainercraft/blob/master/mc_addon/TrainerCraft-BP/entities/bike.json"

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_ble,node_app_entry,node_ws toneBlue
class node_script,node_bike toneAmber
class node_sensor,node_bedrock toneIndigo
```

## Components

### Flutter bridge

- [BLE ingestion](https://github.com/lungmen-hkm/trainercraft/blob/master/app_bridge/lib/services/ble_service.dart): `app_bridge/lib/services/ble_service.dart`
- [App entry](https://github.com/lungmen-hkm/trainercraft/blob/master/app_bridge/lib/main.dart): `app_bridge/lib/main.dart`
- [WebSocket server](https://github.com/lungmen-hkm/trainercraft/blob/master/app_bridge/lib/services/server_service.dart): `app_bridge/lib/services/server_service.dart`

### Minecraft add-on

- [Speed listener and tick loop](https://github.com/lungmen-hkm/trainercraft/blob/master/mc_addon/TrainerCraft-BP/scripts/main.js): `mc_addon/TrainerCraft-BP/scripts/main.js`
- [TrainerCraft bike](https://github.com/lungmen-hkm/trainercraft/blob/master/mc_addon/TrainerCraft-BP/entities/bike.json): `mc_addon/TrainerCraft-BP/entities/bike.json`

### Other components

- **BLE CSC sensor**
- **Bedrock runtime**

## Connections

- BLE CSC sensor → BLE ingestion: sends CSC data
- App entry → BLE ingestion: uses
- App entry → WebSocket server: uses
- BLE ingestion → WebSocket server: provides telemetry
- WebSocket server → Bedrock runtime: broadcasts over WebSocket
- Bedrock runtime → Speed listener and tick loop: delivers speed event
- Speed listener and tick loop → TrainerCraft bike: sets movement