# issuiuc/midas-base architecture

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

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

## Overview

MIDAS-BASE is documented as a combined avionics ground-station repository; the sampled implementation here is its GSS Combiner. Its main workflow selects booster, sustainer, and relay serial sources, reads and processes telemetry, filters and combines packets, and publishes stage data through MQTT. MQTT control messages can be forwarded to telemetry devices, while the GUI provides device selection and session controls. A separate standalone mode and an MQTT-driven GPS map are also present. The root README gives little architecture detail, and several source excerpts are partial, so uncertain wiring is omitted.

Main entry points: [`gss_combiner/main.py`](https://github.com/issuiuc/midas-base/blob/main/gss_combiner/main.py) (Combiner Entrypoint), [`gss_combiner/util/mqtt.py`](https://github.com/issuiuc/midas-base/blob/main/gss_combiner/util/mqtt.py) (Serial Telemetry Threads), [`gss_combiner/util/combiner.py`](https://github.com/issuiuc/midas-base/blob/main/gss_combiner/util/combiner.py) (Stage Combiners), [`gss_combiner/standalone.py`](https://github.com/issuiuc/midas-base/blob/main/gss_combiner/standalone.py) (Standalone Mode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Telemetry Ingest"]
  node_telemetry["Serial Telemetry Threads<br/>[mqtt.py]"]
end

subgraph group_combine["Combining &amp; Publish"]
  node_combiner["Stage Combiners<br/>[combiner.py]"]
  node_mqtt["MQTT Transport<br/>[mqtt.py]"]
end

subgraph group_operate["Ground Station Control"]
  node_main["Combiner Entrypoint<br/>[main.py]"]
  node_gui["Device GUI<br/>[gui_main.py]"]
  node_standalone["Standalone Mode<br/>[standalone.py]"]
end

subgraph group_support["Monitoring &amp; Map"]
  node_logger["Logging &amp; Health<br/>[logger.py]"]
  node_map_subscriber["GPS Map Subscriber<br/>[mappy.py]"]
  node_map_output["Map Output<br/>[mappy.py]"]
end

node_operator(("Operator"))
node_serial_devices(("Serial Devices"))
node_broker(("MQTT Broker"))

node_operator -->|"operates"| node_gui
node_gui -.->|"launches session"| node_main
node_operator -->|"configures sources"| node_main
node_main -->|"creates threads"| node_telemetry
node_main -->|"creates stage filters"| node_combiner
node_main -->|"starts transport"| node_mqtt
node_main -->|"creates streams"| node_logger
node_serial_devices -->|"serial packets"| node_telemetry
node_telemetry -->|"enqueues processed packets"| node_combiner
node_combiner -->|"publishes filtered packets"| node_mqtt
node_mqtt -->|"publishes and subscribes"| node_broker
node_broker -->|"control messages"| node_mqtt
node_mqtt -->|"forwards device commands"| node_telemetry
node_telemetry -->|"writes commands"| node_serial_devices
node_telemetry -->|"records packet activity"| node_logger
node_combiner -->|"records filter activity"| node_logger
node_operator -->|"starts single-port mode"| node_standalone
node_standalone -->|"reads and writes"| node_serial_devices
node_standalone -->|"publishes and subscribes"| node_broker
node_broker -.->|"GPS telemetry"| node_map_subscriber
node_map_subscriber -->|"adds markers"| node_map_output

click node_main "https://github.com/issuiuc/midas-base/blob/main/gss_combiner/main.py"
click node_gui "https://github.com/issuiuc/midas-base/blob/main/gss_combiner/gui_main.py"
click node_standalone "https://github.com/issuiuc/midas-base/blob/main/gss_combiner/standalone.py"
click node_telemetry "https://github.com/issuiuc/midas-base/blob/main/gss_combiner/util/mqtt.py"
click node_combiner "https://github.com/issuiuc/midas-base/blob/main/gss_combiner/util/combiner.py"
click node_mqtt "https://github.com/issuiuc/midas-base/blob/main/gss_combiner/util/mqtt.py"
click node_logger "https://github.com/issuiuc/midas-base/blob/main/gss_combiner/util/logger.py"
click node_map_subscriber "https://github.com/issuiuc/midas-base/blob/main/gss_combiner/util/mappy.py"
click node_map_output "https://github.com/issuiuc/midas-base/blob/main/gss_combiner/util/mappy.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_telemetry toneBlue
class node_combiner,node_mqtt toneAmber
class node_main,node_gui,node_standalone toneMint
class node_logger,node_map_subscriber,node_map_output toneRose
class node_operator,node_serial_devices,node_broker toneIndigo
```

## Components

### Telemetry Ingest

- [Serial Telemetry Threads](https://github.com/issuiuc/midas-base/blob/main/gss_combiner/util/mqtt.py): `gss_combiner/util/mqtt.py`

### Combining & Publish

- [Stage Combiners](https://github.com/issuiuc/midas-base/blob/main/gss_combiner/util/combiner.py): `gss_combiner/util/combiner.py`
- [MQTT Transport](https://github.com/issuiuc/midas-base/blob/main/gss_combiner/util/mqtt.py): `gss_combiner/util/mqtt.py`

### Ground Station Control

- [Combiner Entrypoint](https://github.com/issuiuc/midas-base/blob/main/gss_combiner/main.py): `gss_combiner/main.py`
- [Device GUI](https://github.com/issuiuc/midas-base/blob/main/gss_combiner/gui_main.py): `gss_combiner/gui_main.py`
- [Standalone Mode](https://github.com/issuiuc/midas-base/blob/main/gss_combiner/standalone.py): `gss_combiner/standalone.py`

### Monitoring & Map

- [Logging & Health](https://github.com/issuiuc/midas-base/blob/main/gss_combiner/util/logger.py): `gss_combiner/util/logger.py`
- [GPS Map Subscriber](https://github.com/issuiuc/midas-base/blob/main/gss_combiner/util/mappy.py): `gss_combiner/util/mappy.py`
- [Map Output](https://github.com/issuiuc/midas-base/blob/main/gss_combiner/util/mappy.py): `gss_combiner/util/mappy.py`

### Other components

- **Operator**
- **Serial Devices**
- **MQTT Broker**

## Connections

- Operator → Device GUI: operates
- Device GUI → Combiner Entrypoint: launches session
- Operator → Combiner Entrypoint: configures sources
- Combiner Entrypoint → Serial Telemetry Threads: creates threads
- Combiner Entrypoint → Stage Combiners: creates stage filters
- Combiner Entrypoint → MQTT Transport: starts transport
- Combiner Entrypoint → Logging & Health: creates streams
- Serial Devices → Serial Telemetry Threads: serial packets
- Serial Telemetry Threads → Stage Combiners: enqueues processed packets
- Stage Combiners → MQTT Transport: publishes filtered packets
- MQTT Transport → MQTT Broker: publishes and subscribes
- MQTT Broker → MQTT Transport: control messages
- MQTT Transport → Serial Telemetry Threads: forwards device commands
- Serial Telemetry Threads → Serial Devices: writes commands
- Serial Telemetry Threads → Logging & Health: records packet activity
- Stage Combiners → Logging & Health: records filter activity
- Operator → Standalone Mode: starts single-port mode
- Standalone Mode → Serial Devices: reads and writes
- Standalone Mode → MQTT Broker: publishes and subscribes
- MQTT Broker → GPS Map Subscriber: GPS telemetry
- GPS Map Subscriber → Map Output: adds markers