# conductors-senior-project-rit/detector-station architecture

> Architecture diagram of the GitHub repository conductors-senior-project-rit/detector-station, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/conductors-senior-project-rit/detector-station
- Repository: https://github.com/conductors-senior-project-rit/detector-station

## Overview

TrackSense is a desktop telemetry receiver for End-of-Train (EOT) and Head-of-Train (HOT) radio data. An operator starts tracking in the Qt interface; the handler consumes bit data published by the GNU Radio workflow, recognizes frames, decodes valid packets, updates the live table and local logs, and optionally posts telemetry to the server. Failed posts are retained and replayed, while a separate heartbeat reports station availability. The excerpts support the main runtime links; some UI details, handler setup, and configuration values were not sampled, so those relationships are kept at subsystem level.

Main entry points: [`standalone_app/EOT/eot_handler.py`](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/eot_handler.py) (EOT handler), [`standalone_app/QtGUI/TrackSenseGUIWrapper.py`](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/QtGUI/TrackSenseGUIWrapper.py) (GUI wrapper), [`standalone_app/EOT/information_sender.py`](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/information_sender.py) (Telemetry requests), [`standalone_app/EOT/dropped_data_handler.py`](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/dropped_data_handler.py) (Dropped-data handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop UI"]
  node_app["App entry<br/>[main.py]"]
  node_gui["GUI wrapper"]
  node_ui["Qt interface<br/>[TrackSenseGUI.py]"]
end

subgraph group_telemetry["Telemetry processing"]
  node_handler["EOT handler<br/>[eot_handler.py]"]
  node_workflow["GNU Radio source"]
  node_decoders["EOT/HOT decoders<br/>[decoders.py]"]
end

subgraph group_delivery["Server delivery"]
  node_request["Telemetry requests"]
  node_drop_handler["Dropped-data handler"]
  node_drop_file["Dropped packets<br/>[dropped_data.json]"]
  node_heartbeat["Heartbeat worker<br/>[ping.py]"]
end

subgraph group_local["Local monitoring"]
  node_audio["Audio monitor<br/>[audio_amplitude.py]"]
  node_logs["Local logs"]
  node_text_logs["Telemetry text logs<br/>[eot_handler.py]"]
end

node_operator(("Operator"))
node_api["TrackSense API"]

node_operator -->|"operates"| node_ui
node_app -->|"creates"| node_gui
node_gui -->|"sets up"| node_ui
node_gui -->|"starts tracking"| node_handler
node_workflow -->|"publishes bits"| node_handler
node_handler -->|"decodes frames"| node_decoders
node_handler -->|"emits table data"| node_gui
node_gui -->|"starts monitoring"| node_audio
node_audio -->|"emits level"| node_gui
node_handler -->|"dispatches packets"| node_request
node_request -->|"posts history"| node_api
node_request -->|"saves failures"| node_drop_handler
node_request -->|"requests replay"| node_drop_handler
node_drop_handler -->|"reads/writes"| node_drop_file
node_drop_handler -->|"replays history"| node_api
node_handler -->|"starts heartbeat"| node_heartbeat
node_heartbeat -->|"posts status"| node_api
node_handler -->|"writes telemetry"| node_text_logs
node_gui -->|"logs events"| node_logs
node_handler -->|"logs events"| node_logs

click node_app "https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/main.py"
click node_gui "https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/QtGUI/TrackSenseGUIWrapper.py"
click node_ui "https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/QtGUI/TrackSenseGUI.py"
click node_handler "https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/eot_handler.py"
click node_workflow "https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/TrackSenseGNURadioWorkflow.grc"
click node_decoders "https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/decoders.py"
click node_audio "https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/audio_amplitude.py"
click node_request "https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/information_sender.py"
click node_drop_handler "https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/dropped_data_handler.py"
click node_drop_file "https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/dist/dropped_data.json"
click node_heartbeat "https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/ping.py"
click node_logs "https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/TrackSenseLogger.py"
click node_text_logs "https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/eot_handler.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_app,node_gui,node_ui toneBlue
class node_handler,node_workflow,node_decoders toneAmber
class node_request,node_drop_handler,node_drop_file,node_heartbeat,node_api toneMint
class node_audio,node_logs,node_text_logs toneRose
class node_operator toneIndigo
```

## Components

### Desktop UI

- [App entry](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/main.py): `standalone_app/main.py`
- [GUI wrapper](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/QtGUI/TrackSenseGUIWrapper.py): `standalone_app/QtGUI/TrackSenseGUIWrapper.py`
- [Qt interface](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/QtGUI/TrackSenseGUI.py): `standalone_app/QtGUI/TrackSenseGUI.py`

### Telemetry processing

- [EOT handler](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/eot_handler.py): `standalone_app/EOT/eot_handler.py`
- [GNU Radio source](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/TrackSenseGNURadioWorkflow.grc): `standalone_app/TrackSenseGNURadioWorkflow.grc`
- [EOT/HOT decoders](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/decoders.py): `standalone_app/EOT/decoders.py`

### Server delivery

- [Telemetry requests](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/information_sender.py): `standalone_app/EOT/information_sender.py`
- [Dropped-data handler](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/dropped_data_handler.py): `standalone_app/EOT/dropped_data_handler.py`
- [Dropped packets](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/dist/dropped_data.json): `standalone_app/dist/dropped_data.json`
- [Heartbeat worker](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/ping.py): `standalone_app/EOT/ping.py`

### Local monitoring

- [Audio monitor](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/audio_amplitude.py): `standalone_app/EOT/audio_amplitude.py`
- [Local logs](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/TrackSenseLogger.py): `standalone_app/TrackSenseLogger.py`
- [Telemetry text logs](https://github.com/conductors-senior-project-rit/detector-station/blob/main/standalone_app/EOT/eot_handler.py): `standalone_app/EOT/eot_handler.py`

### Other components

- **Operator**
- **TrackSense API**

## Connections

- Operator → Qt interface: operates
- App entry → GUI wrapper: creates
- GUI wrapper → Qt interface: sets up
- GUI wrapper → EOT handler: starts tracking
- GNU Radio source → EOT handler: publishes bits
- EOT handler → EOT/HOT decoders: decodes frames
- EOT handler → GUI wrapper: emits table data
- GUI wrapper → Audio monitor: starts monitoring
- Audio monitor → GUI wrapper: emits level
- EOT handler → Telemetry requests: dispatches packets
- Telemetry requests → TrackSense API: posts history
- Telemetry requests → Dropped-data handler: saves failures
- Telemetry requests → Dropped-data handler: requests replay
- Dropped-data handler → Dropped packets: reads/writes
- Dropped-data handler → TrackSense API: replays history
- EOT handler → Heartbeat worker: starts heartbeat
- Heartbeat worker → TrackSense API: posts status
- EOT handler → Telemetry text logs: writes telemetry
- GUI wrapper → Local logs: logs events
- EOT handler → Local logs: logs events