# marcle-bert26-ui/fs-telemetry architecture

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

- Interactive diagram: https://gitdiagram.com/marcle-bert26-ui/fs-telemetry
- Repository: https://github.com/marcle-bert26-ui/fs-telemetry

## Overview

EIGSI Formula Student Telemetry is a desktop and console system for acquiring vehicle telemetry, recording it, replaying runs, and analyzing them. The principal GUI workflow starts in the live or replay mode, reads serial or CSV data, parses and manages telemetry, then updates displays and visualizations; live data is also logged to CSV. The README documents GPS track mapping and fuel analysis alongside charts and G-force views. Some visualization wiring is documented rather than visible in sampled source, so those edges cite the README; other unsampled details are omitted.

Main entry points: [`src/gui/live_mode_widget.py`](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/gui/live_mode_widget.py) (Live mode), [`src/main.py`](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/main.py) (Console workflow), [`src/gui/replay_mode_widget.py`](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/gui/replay_mode_widget.py) (Replay mode), [`src/gui/main_window.py`](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/gui/main_window.py) (Main window)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_gui_app["GUI launcher<br/>[gui_app.py]"]
  node_cli["Console workflow<br/>[main.py]"]
end

subgraph group_acquisition["Acquisition and data"]
  node_serial_source["Serial source<br/>[serial_source.py]"]
  node_csv_source["CSV source<br/>[csv_source.py]"]
  node_parser["Telemetry parser<br/>[csv_parser.py]"]
  node_manager["Telemetry manager"]
  node_csv_logger[("CSV logger<br/>[csv_logger.py]")]
end

subgraph group_gui["Desktop experience"]
  node_main_window["Main window<br/>[main_window.py]"]
  node_live["Live mode"]
  node_replay["Replay mode"]
  node_file_selector["File selector"]
end

subgraph group_analysis["Analysis and visualization"]
  node_charts["Telemetry charts"]
  node_temporal["Temporal analysis"]
  node_spider["G-force spider<br/>[spider_charts.py]"]
  node_track_map["GPS track map<br/>[track_map.py]"]
  node_injection_table["Fuel injection data"]
  node_console_display["Console display<br/>[console_display.py]"]
end

node_driver(("Vehicle operator"))
node_arduino(("Arduino / serial"))

node_driver -->|"launches"| node_gui_app
node_gui_app -->|"opens"| node_main_window
node_driver -.->|"uses"| node_main_window
node_main_window -->|"hosts"| node_live
node_main_window -->|"hosts"| node_replay
node_main_window -->|"hosts"| node_file_selector
node_arduino -->|"sends telemetry"| node_serial_source
node_live -->|"reads"| node_serial_source
node_live -->|"parses"| node_parser
node_live -->|"updates"| node_manager
node_live -->|"logs data"| node_csv_logger
node_live -->|"updates"| node_charts
node_live -->|"updates"| node_temporal
node_live -->|"shows position"| node_track_map
node_replay -->|"selects file"| node_file_selector
node_replay -->|"reads run"| node_csv_source
node_replay -->|"parses"| node_parser
node_replay -->|"updates"| node_manager
node_replay -->|"updates"| node_charts
node_replay -->|"updates"| node_temporal
node_temporal -->|"displays forces"| node_spider
node_temporal -->|"displays trajectory"| node_track_map
node_charts -->|"uses fuel data"| node_injection_table
node_driver -->|"runs"| node_cli
node_cli -->|"reads live data"| node_serial_source
node_cli -->|"reads replay"| node_csv_source
node_cli -->|"parses"| node_parser
node_cli -->|"updates"| node_manager
node_cli -->|"logs live data"| node_csv_logger
node_cli -->|"displays data"| node_console_display

click node_gui_app "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/gui_app.py"
click node_main_window "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/gui/main_window.py"
click node_live "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/gui/live_mode_widget.py"
click node_replay "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/gui/replay_mode_widget.py"
click node_file_selector "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/gui/file_selector_widget.py"
click node_serial_source "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/sources/serial_source.py"
click node_csv_source "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/data/csv_source.py"
click node_parser "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/data/csv_parser.py"
click node_manager "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/core/telemetry_manager.py"
click node_csv_logger "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/data/csv_logger.py"
click node_charts "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/visualization/telemetry_charts.py"
click node_temporal "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/gui/temporal_analysis_widget.py"
click node_spider "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/visualization/spider_charts.py"
click node_track_map "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/visualization/track_map.py"
click node_injection_table "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/tools/ecu_injection_table.py"
click node_cli "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/main.py"
click node_console_display "https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/utils/console_display.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_gui_app,node_cli toneBlue
class node_serial_source,node_csv_source,node_parser,node_manager,node_csv_logger toneAmber
class node_main_window,node_live,node_replay,node_file_selector toneMint
class node_charts,node_temporal,node_spider,node_track_map,node_injection_table,node_console_display toneRose
class node_driver,node_arduino toneIndigo
```

## Components

### Application entry

- [GUI launcher](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/gui_app.py): `src/gui_app.py`
- [Console workflow](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/main.py): `src/main.py`

### Acquisition and data

- [Serial source](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/sources/serial_source.py): `src/sources/serial_source.py`
- [CSV source](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/data/csv_source.py): `src/data/csv_source.py`
- [Telemetry parser](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/data/csv_parser.py): `src/data/csv_parser.py`
- [Telemetry manager](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/core/telemetry_manager.py): `src/core/telemetry_manager.py`
- [CSV logger](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/data/csv_logger.py): `src/data/csv_logger.py`

### Desktop experience

- [Main window](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/gui/main_window.py): `src/gui/main_window.py`
- [Live mode](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/gui/live_mode_widget.py): `src/gui/live_mode_widget.py`
- [Replay mode](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/gui/replay_mode_widget.py): `src/gui/replay_mode_widget.py`
- [File selector](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/gui/file_selector_widget.py): `src/gui/file_selector_widget.py`

### Analysis and visualization

- [Telemetry charts](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/visualization/telemetry_charts.py): `src/visualization/telemetry_charts.py`
- [Temporal analysis](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/gui/temporal_analysis_widget.py): `src/gui/temporal_analysis_widget.py`
- [G-force spider](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/visualization/spider_charts.py): `src/visualization/spider_charts.py`
- [GPS track map](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/visualization/track_map.py): `visualization/track_map.py`
- [Fuel injection data](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/tools/ecu_injection_table.py): `tools/ecu_injection_table.py`
- [Console display](https://github.com/marcle-bert26-ui/fs-telemetry/blob/main/src/utils/console_display.py): `src/utils/console_display.py`

### Other components

- **Vehicle operator**
- **Arduino / serial**

## Connections

- Vehicle operator → GUI launcher: launches
- GUI launcher → Main window: opens (evidence: `src/gui_app.py`)
- Vehicle operator → Main window: uses
- Main window → Live mode: hosts (evidence: `src/gui/main_window.py`)
- Main window → Replay mode: hosts (evidence: `src/gui/main_window.py`)
- Main window → File selector: hosts (evidence: `src/gui/main_window.py`)
- Arduino / serial → Serial source: sends telemetry (evidence: `src/sources/serial_source.py`)
- Live mode → Serial source: reads (evidence: `src/gui/live_mode_widget.py`)
- Live mode → Telemetry parser: parses (evidence: `src/gui/live_mode_widget.py`)
- Live mode → Telemetry manager: updates (evidence: `src/gui/live_mode_widget.py`)
- Live mode → CSV logger: logs data (evidence: `src/gui/live_mode_widget.py`)
- Live mode → Telemetry charts: updates (evidence: `src/gui/live_mode_widget.py`)
- Live mode → Temporal analysis: updates (evidence: `src/gui/live_mode_widget.py`)
- Live mode → GPS track map: shows position
- Replay mode → File selector: selects file (evidence: `src/gui/replay_mode_widget.py`)
- Replay mode → CSV source: reads run (evidence: `src/gui/replay_mode_widget.py`)
- Replay mode → Telemetry parser: parses (evidence: `src/gui/replay_mode_widget.py`)
- Replay mode → Telemetry manager: updates (evidence: `src/gui/replay_mode_widget.py`)
- Replay mode → Telemetry charts: updates (evidence: `src/gui/replay_mode_widget.py`)
- Replay mode → Temporal analysis: updates (evidence: `src/gui/replay_mode_widget.py`)
- Temporal analysis → G-force spider: displays forces (evidence: `src/gui/temporal_analysis_widget.py`)
- Temporal analysis → GPS track map: displays trajectory
- Telemetry charts → Fuel injection data: uses fuel data (evidence: `src/visualization/telemetry_charts.py`)
- Vehicle operator → Console workflow: runs
- Console workflow → Serial source: reads live data (evidence: `src/main.py`)
- Console workflow → CSV source: reads replay (evidence: `src/main.py`)
- Console workflow → Telemetry parser: parses (evidence: `src/main.py`)
- Console workflow → Telemetry manager: updates (evidence: `src/main.py`)
- Console workflow → CSV logger: logs live data (evidence: `src/main.py`)
- Console workflow → Console display: displays data (evidence: `src/main.py`)
