# issuiuc/groundstation architecture

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

- Interactive diagram: https://gitdiagram.com/issuiuc/groundstation
- Repository: https://github.com/issuiuc/groundstation

## Overview

GSS is a ground-station application for viewing rocket telemetry, issuing commands, monitoring system health, and producing livestream overlays; it also includes backend relay and video services. The primary user workflow runs through the frontend app into telemetry/commanding views, with telemetry supplied by a shared data provider and command actions sent from the commanding view. Stream overlays and OBS controls are separate product branches. Relationships involving unsampled backend and video internals are not asserted; dashed links mark the documented but incompletely evidenced MQTT integration.

Main entry points: [`gss-frontend/src/components/dataflow/gssdata.jsx`](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/dataflow/gssdata.jsx) (Telemetry Provider), [`gss-frontend/src/app.jsx`](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/app.jsx) (Frontend App), [`gss-frontend/src/components/streamoverlay/OverlayController.jsx`](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/streamoverlay/OverlayController.jsx) (Stream Overlay), [`gss-frontend/src/components/streamcontrol/StreamControlPanel.jsx`](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/streamcontrol/StreamControlPanel.jsx) (Stream Control Panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Ground Station UI"]
  node_app["Frontend App<br/>[app.jsx]"]
  node_telemetry_views["Telemetry Views"]
  node_map["Map View<br/>[MapView.jsx]"]
  node_health["System Health"]
  node_commanding["Commanding View<br/>[CommandingView.jsx]"]
  node_settings_view["Settings View<br/>[SettingsView.jsx]"]
end

subgraph group_data["Telemetry And Commands"]
  node_data_provider["Telemetry Provider<br/>[gssdata.jsx]"]
  node_settings["Data Settings<br/>[settings.jsx]"]
  node_sequencer["Event Sequencer<br/>[sequencer.jsx]"]
  node_derivatives["Telemetry Derivatives<br/>[derivatives.jsx]"]
  node_midas["MIDAS Conversion"]
  node_feedback["Command Feedback"]
end

subgraph group_stream["Livestream Control"]
  node_overlay["Stream Overlay"]
  node_countdown["Overlay Countdown<br/>[CountdownTimer.jsx]"]
  node_stream_control["Stream Control Panel"]
  node_obs_service["OBS Service<br/>[obsService.js]"]
  node_format_loader["Stream Format Loader"]
end

subgraph group_services["Backend Services"]
  node_backend["Backend Entry<br/>[main.py]"]
  node_mqtt_relay["MQTT Relay<br/>[relay_mqtt.py]"]
  node_video_service["Video Service<br/>[main.py]"]
end

node_operator(("Operator"))
node_mqtt_broker[("MQTT Broker")]
node_obs["OBS"]

node_operator -->|"uses"| node_app
node_app -->|"provides context"| node_data_provider
node_app -->|"routes to"| node_telemetry_views
node_app -->|"routes to"| node_map
node_app -->|"routes to"| node_health
node_app -->|"routes to"| node_commanding
node_app -->|"routes to"| node_settings_view
node_app -->|"routes to"| node_overlay
node_map -->|"reads telemetry"| node_data_provider
node_health -->|"reads telemetry"| node_data_provider
node_commanding -->|"reads and sends"| node_data_provider
node_commanding -->|"requests feedback"| node_feedback
node_data_provider -->|"reads settings"| node_settings
node_data_provider -->|"updates events"| node_sequencer
node_overlay -->|"reads telemetry"| node_data_provider
node_overlay -->|"renders"| node_countdown
node_overlay -->|"uses conversion"| node_midas
node_stream_control -->|"reads and syncs"| node_data_provider
node_stream_control -->|"controls"| node_obs_service
node_stream_control -->|"loads presets"| node_format_loader
node_obs_service -->|"connects and calls"| node_obs
node_backend -->|"imports"| node_mqtt_relay
node_data_provider -.->|"exchanges packets"| node_mqtt_broker
node_mqtt_relay -.->|"relays packets"| node_mqtt_broker

click node_app "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/app.jsx"
click node_telemetry_views "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/views/FullTelemetryView.jsx"
click node_map "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/views/MapView.jsx"
click node_health "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/views/SystemHealthView.jsx"
click node_commanding "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/views/CommandingView.jsx"
click node_settings_view "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/views/SettingsView.jsx"
click node_data_provider "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/dataflow/gssdata.jsx"
click node_settings "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/dataflow/settings.jsx"
click node_sequencer "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/dataflow/sequencer.jsx"
click node_derivatives "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/dataflow/derivatives.jsx"
click node_midas "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/dataflow/midasconversion.jsx"
click node_feedback "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/spec/CommandFeedback.jsx"
click node_overlay "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/streamoverlay/OverlayController.jsx"
click node_countdown "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/streamoverlay/CountdownTimer.jsx"
click node_stream_control "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/streamcontrol/StreamControlPanel.jsx"
click node_obs_service "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/services/obsService.js"
click node_format_loader "https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/services/streamFormatLoader.js"
click node_backend "https://github.com/issuiuc/groundstation/blob/main/gss-backend/main.py"
click node_mqtt_relay "https://github.com/issuiuc/groundstation/blob/main/gss-backend/util/relay_mqtt.py"
click node_video_service "https://github.com/issuiuc/groundstation/blob/main/gss-video/main.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_telemetry_views,node_map,node_health,node_commanding,node_settings_view toneBlue
class node_data_provider,node_settings,node_sequencer,node_derivatives,node_midas,node_feedback,node_mqtt_broker toneAmber
class node_overlay,node_countdown,node_stream_control,node_obs_service,node_format_loader toneMint
class node_backend,node_mqtt_relay,node_video_service toneRose
class node_operator,node_obs toneIndigo
```

## Components

### Ground Station UI

- [Frontend App](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/app.jsx): `gss-frontend/src/app.jsx`
- [Telemetry Views](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/views/FullTelemetryView.jsx): `gss-frontend/src/components/views/FullTelemetryView.jsx`
- [Map View](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/views/MapView.jsx): `gss-frontend/src/components/views/MapView.jsx`
- [System Health](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/views/SystemHealthView.jsx): `gss-frontend/src/components/views/SystemHealthView.jsx`
- [Commanding View](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/views/CommandingView.jsx): `gss-frontend/src/components/views/CommandingView.jsx`
- [Settings View](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/views/SettingsView.jsx): `gss-frontend/src/components/views/SettingsView.jsx`

### Telemetry And Commands

- [Telemetry Provider](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/dataflow/gssdata.jsx): `gss-frontend/src/components/dataflow/gssdata.jsx`
- [Data Settings](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/dataflow/settings.jsx): `gss-frontend/src/components/dataflow/settings.jsx`
- [Event Sequencer](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/dataflow/sequencer.jsx): `gss-frontend/src/components/dataflow/sequencer.jsx`
- [Telemetry Derivatives](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/dataflow/derivatives.jsx): `gss-frontend/src/components/dataflow/derivatives.jsx`
- [MIDAS Conversion](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/dataflow/midasconversion.jsx): `gss-frontend/src/components/dataflow/midasconversion.jsx`
- [Command Feedback](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/spec/CommandFeedback.jsx): `gss-frontend/src/components/spec/CommandFeedback.jsx`

### Livestream Control

- [Stream Overlay](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/streamoverlay/OverlayController.jsx): `gss-frontend/src/components/streamoverlay/OverlayController.jsx`
- [Overlay Countdown](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/streamoverlay/CountdownTimer.jsx): `gss-frontend/src/components/streamoverlay/CountdownTimer.jsx`
- [Stream Control Panel](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/components/streamcontrol/StreamControlPanel.jsx): `gss-frontend/src/components/streamcontrol/StreamControlPanel.jsx`
- [OBS Service](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/services/obsService.js): `gss-frontend/src/services/obsService.js`
- [Stream Format Loader](https://github.com/issuiuc/groundstation/blob/main/gss-frontend/src/services/streamFormatLoader.js): `gss-frontend/src/services/streamFormatLoader.js`

### Backend Services

- [Backend Entry](https://github.com/issuiuc/groundstation/blob/main/gss-backend/main.py): `gss-backend/main.py`
- [MQTT Relay](https://github.com/issuiuc/groundstation/blob/main/gss-backend/util/relay_mqtt.py): `gss-backend/util/relay_mqtt.py`
- [Video Service](https://github.com/issuiuc/groundstation/blob/main/gss-video/main.py): `gss-video/main.py`

### Other components

- **Operator**
- **MQTT Broker**
- **OBS**

## Connections

- Operator → Frontend App: uses (evidence: `gss-frontend/src/app.jsx`)
- Frontend App → Telemetry Provider: provides context (evidence: `gss-frontend/src/app.jsx`)
- Frontend App → Telemetry Views: routes to (evidence: `gss-frontend/src/app.jsx`)
- Frontend App → Map View: routes to (evidence: `gss-frontend/src/app.jsx`)
- Frontend App → System Health: routes to (evidence: `gss-frontend/src/app.jsx`)
- Frontend App → Commanding View: routes to (evidence: `gss-frontend/src/app.jsx`)
- Frontend App → Settings View: routes to (evidence: `gss-frontend/src/app.jsx`)
- Frontend App → Stream Overlay: routes to (evidence: `gss-frontend/src/app.jsx`)
- Map View → Telemetry Provider: reads telemetry (evidence: `gss-frontend/src/components/views/MapView.jsx`)
- System Health → Telemetry Provider: reads telemetry (evidence: `gss-frontend/src/components/views/SystemHealthView.jsx`)
- Commanding View → Telemetry Provider: reads and sends (evidence: `gss-frontend/src/components/views/CommandingView.jsx`)
- Commanding View → Command Feedback: requests feedback (evidence: `gss-frontend/src/components/views/CommandingView.jsx`)
- Telemetry Provider → Data Settings: reads settings (evidence: `gss-frontend/src/components/dataflow/gssdata.jsx`)
- Telemetry Provider → Event Sequencer: updates events (evidence: `gss-frontend/src/components/dataflow/gssdata.jsx`)
- Stream Overlay → Telemetry Provider: reads telemetry (evidence: `gss-frontend/src/components/streamoverlay/OverlayController.jsx`)
- Stream Overlay → Overlay Countdown: renders (evidence: `gss-frontend/src/components/streamoverlay/OverlayController.jsx`)
- Stream Overlay → MIDAS Conversion: uses conversion (evidence: `gss-frontend/src/components/streamoverlay/OverlayController.jsx`)
- Stream Control Panel → Telemetry Provider: reads and syncs (evidence: `gss-frontend/src/components/streamcontrol/StreamControlPanel.jsx`)
- Stream Control Panel → OBS Service: controls (evidence: `gss-frontend/src/components/streamcontrol/StreamControlPanel.jsx`)
- Stream Control Panel → Stream Format Loader: loads presets
- OBS Service → OBS: connects and calls (evidence: `gss-frontend/src/services/obsService.js`)
- Backend Entry → MQTT Relay: imports (evidence: `gss-backend/main.py`)
- Telemetry Provider → MQTT Broker: exchanges packets
- MQTT Relay → MQTT Broker: relays packets