# avneeshw/twin-athlete architecture

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

- Interactive diagram: https://gitdiagram.com/avneeshw/twin-athlete
- Repository: https://github.com/avneeshw/twin-athlete

## Overview

Twin-Athlete is a sports-performance digital-twin platform: sensor or demo telemetry is validated and analyzed, used to update athlete state and forecasts, then surfaced through athlete, coach, and auditor views. The graph preserves documented scenario simulation, squad management, model-card, and feedback-ledger capabilities. Some subsystem links are based on README statements; unsampled implementation details are not inferred.

Main entry points: [`app.py`](https://github.com/avneeshw/twin-athlete/blob/main/app.py) (REST / Stream API), [`twin/coach.py`](https://github.com/avneeshw/twin-athlete/blob/main/twin/coach.py) (Athlete Twin & Coach), [`static/app.js`](https://github.com/avneeshw/twin-athlete/blob/main/static/app.js) (Role Cockpit), [`twin/storage.py`](https://github.com/avneeshw/twin-athlete/blob/main/twin/storage.py) (SQLite Vault)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Telemetry Ingestion"]
  node_hardware["ESP32 Sensors"]
  node_contracts["Packet Contracts<br/>[contracts.py]"]
  node_telemetry["Signal Pipeline<br/>[telemetry.py]"]
end

subgraph group_analytics["Twin Analytics"]
  node_coach["Athlete Twin &amp; Coach<br/>[coach.py]"]
  node_simulator["Scenario Simulator<br/>[simulator.py]"]
  node_model_artifacts["Forecast Models"]
  node_data_generator["Synthetic Data Generator<br/>[generate_data.py]"]
  node_compat["Data Compatibility<br/>[compat.py]"]
  node_feedback["Prediction Feedback Ledger<br/>[coach.py]"]
end

subgraph group_platform["Athlete Platform"]
  node_api["REST / Stream API<br/>[app.py]"]
  node_registry["Squad Registry<br/>[registry.py]"]
  node_storage[("SQLite Vault<br/>[storage.py]")]
end

subgraph group_experience["Role Cockpit"]
  node_dashboard["Role Cockpit<br/>[app.js]"]
  node_web_shell["Cockpit Interface<br/>[index.html]"]
end

node_athlete(("Athlete"))
node_coach_user(("Coach / Scientist"))

node_athlete -.->|"wears sensors"| node_hardware
node_hardware -.->|"sends packets"| node_contracts
node_api -->|"validates payloads"| node_contracts
node_telemetry -->|"validates packets"| node_contracts
node_api -->|"processes telemetry"| node_telemetry
node_api -->|"requests twin metrics"| node_coach
node_api -->|"reads squad data"| node_registry
node_api -->|"runs scenarios"| node_simulator
node_api -->|"generates datasets"| node_data_generator
node_coach -->|"loads and saves profiles"| node_storage
node_coach -->|"persists outcomes"| node_storage
node_registry -->|"creates athlete twins"| node_coach
node_registry -->|"reads device mappings"| node_storage
node_simulator -.->|"loads forecasts"| node_model_artifacts
node_data_generator -->|"uses dataframe support"| node_compat
node_athlete -->|"views personal cockpit"| node_dashboard
node_coach_user -->|"views squad matrix"| node_dashboard
node_coach_user -->|"reviews diagnostics"| node_dashboard
node_api -->|"streams live telemetry"| node_dashboard
node_web_shell -.->|"hosts cockpit"| node_dashboard
node_coach -->|"tracks predictions"| node_feedback
node_feedback -->|"loads ledger records"| node_storage

click node_hardware "https://github.com/avneeshw/twin-athlete/blob/main/firmware/esp32_athlete_tracker/esp32_athlete_tracker.ino"
click node_contracts "https://github.com/avneeshw/twin-athlete/blob/main/twin/contracts.py"
click node_telemetry "https://github.com/avneeshw/twin-athlete/blob/main/twin/telemetry.py"
click node_api "https://github.com/avneeshw/twin-athlete/blob/main/app.py"
click node_coach "https://github.com/avneeshw/twin-athlete/blob/main/twin/coach.py"
click node_registry "https://github.com/avneeshw/twin-athlete/blob/main/twin/registry.py"
click node_simulator "https://github.com/avneeshw/twin-athlete/blob/main/twin/simulator.py"
click node_model_artifacts "https://github.com/avneeshw/twin-athlete/blob/main/ml/models/twin_fatigue_model.pkl"
click node_data_generator "https://github.com/avneeshw/twin-athlete/blob/main/ml/generate_data.py"
click node_storage "https://github.com/avneeshw/twin-athlete/blob/main/twin/storage.py"
click node_compat "https://github.com/avneeshw/twin-athlete/blob/main/twin/compat.py"
click node_dashboard "https://github.com/avneeshw/twin-athlete/blob/main/static/app.js"
click node_web_shell "https://github.com/avneeshw/twin-athlete/blob/main/static/index.html"
click node_feedback "https://github.com/avneeshw/twin-athlete/blob/main/twin/coach.py"

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_hardware,node_contracts,node_telemetry toneBlue
class node_coach,node_simulator,node_model_artifacts,node_data_generator,node_compat,node_feedback toneAmber
class node_api,node_registry,node_storage toneMint
class node_dashboard,node_web_shell toneRose
class node_athlete,node_coach_user toneIndigo
```

## Components

### Telemetry Ingestion

- [ESP32 Sensors](https://github.com/avneeshw/twin-athlete/blob/main/firmware/esp32_athlete_tracker/esp32_athlete_tracker.ino): `firmware/esp32_athlete_tracker/esp32_athlete_tracker.ino`
- [Packet Contracts](https://github.com/avneeshw/twin-athlete/blob/main/twin/contracts.py): `twin/contracts.py`
- [Signal Pipeline](https://github.com/avneeshw/twin-athlete/blob/main/twin/telemetry.py): `twin/telemetry.py`

### Twin Analytics

- [Athlete Twin & Coach](https://github.com/avneeshw/twin-athlete/blob/main/twin/coach.py): `twin/coach.py`
- [Scenario Simulator](https://github.com/avneeshw/twin-athlete/blob/main/twin/simulator.py): `twin/simulator.py`
- [Forecast Models](https://github.com/avneeshw/twin-athlete/blob/main/ml/models/twin_fatigue_model.pkl): `ml/models/twin_fatigue_model.pkl`
- [Synthetic Data Generator](https://github.com/avneeshw/twin-athlete/blob/main/ml/generate_data.py): `ml/generate_data.py`
- [Data Compatibility](https://github.com/avneeshw/twin-athlete/blob/main/twin/compat.py): `twin/compat.py`
- [Prediction Feedback Ledger](https://github.com/avneeshw/twin-athlete/blob/main/twin/coach.py): `twin/coach.py`

### Athlete Platform

- [REST / Stream API](https://github.com/avneeshw/twin-athlete/blob/main/app.py): `app.py`
- [Squad Registry](https://github.com/avneeshw/twin-athlete/blob/main/twin/registry.py): `twin/registry.py`
- [SQLite Vault](https://github.com/avneeshw/twin-athlete/blob/main/twin/storage.py): `twin/storage.py`

### Role Cockpit

- [Role Cockpit](https://github.com/avneeshw/twin-athlete/blob/main/static/app.js): `static/app.js`
- [Cockpit Interface](https://github.com/avneeshw/twin-athlete/blob/main/static/index.html): `static/index.html`

### Other components

- **Athlete**
- **Coach / Scientist**

## Connections

- Athlete → ESP32 Sensors: wears sensors (evidence: `README.md`)
- ESP32 Sensors → Packet Contracts: sends packets (evidence: `README.md`)
- REST / Stream API → Packet Contracts: validates payloads (evidence: `app.py`)
- Signal Pipeline → Packet Contracts: validates packets (evidence: `twin/telemetry.py`)
- REST / Stream API → Signal Pipeline: processes telemetry (evidence: `app.py`)
- REST / Stream API → Athlete Twin & Coach: requests twin metrics (evidence: `app.py`)
- REST / Stream API → Squad Registry: reads squad data (evidence: `app.py`)
- REST / Stream API → Scenario Simulator: runs scenarios (evidence: `app.py`)
- REST / Stream API → Synthetic Data Generator: generates datasets (evidence: `app.py`)
- Athlete Twin & Coach → SQLite Vault: loads and saves profiles (evidence: `twin/coach.py`)
- Athlete Twin & Coach → SQLite Vault: persists outcomes (evidence: `twin/coach.py`)
- Squad Registry → Athlete Twin & Coach: creates athlete twins (evidence: `twin/registry.py`)
- Squad Registry → SQLite Vault: reads device mappings (evidence: `twin/registry.py`)
- Scenario Simulator → Forecast Models: loads forecasts
- Synthetic Data Generator → Data Compatibility: uses dataframe support (evidence: `ml/generate_data.py`)
- Athlete → Role Cockpit: views personal cockpit (evidence: `README.md`)
- Coach / Scientist → Role Cockpit: views squad matrix (evidence: `README.md`)
- Coach / Scientist → Role Cockpit: reviews diagnostics (evidence: `README.md`)
- REST / Stream API → Role Cockpit: streams live telemetry (evidence: `app.py`)
- Cockpit Interface → Role Cockpit: hosts cockpit
- Athlete Twin & Coach → Prediction Feedback Ledger: tracks predictions (evidence: `twin/coach.py`)
- Prediction Feedback Ledger → SQLite Vault: loads ledger records (evidence: `twin/coach.py`)
