# blockstream/satellite architecture

> Architecture diagram of the GitHub repository blockstream/satellite, 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/blockstream/satellite
- Repository: https://github.com/blockstream/satellite

## Overview

Blockstream Satellite CLI and GUI prepare and manage a satellite receiver, then support receiving broadcast data and using the Satellite API. The main user workflow is configure receiver hardware and software, establish reception, and run the Bitcoin/Satellite API applications. Separate capabilities include monitoring and API message transmission/management, including encrypted messages and Lightning payment. The graph reflects README-documented capabilities and source-index references; many implementations were not excerpted, so uncertain runtime wiring is omitted.

Main entry points: [`blocksatcli/main.py`](https://github.com/blockstream/satellite/blob/master/blocksatcli/main.py) (CLI commands), [`blocksatcli/api/api.py`](https://github.com/blockstream/satellite/blob/master/blocksatcli/api/api.py) (API command handlers), [`blocksatgui/receiver/dashboard.py`](https://github.com/blockstream/satellite/blob/master/blocksatgui/receiver/dashboard.py) (Receiver dashboard), [`blocksatgui/main.py`](https://github.com/blockstream/satellite/blob/master/blocksatgui/main.py) (GUI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI commands<br/>[main.py]"]
  node_gui["GUI application<br/>[main.py]"]
  node_guiwindow["Main window<br/>[mainwindow.py]"]
  node_rxdashboard["Receiver dashboard<br/>[dashboard.py]"]
  node_satapidialogs["API dialogs<br/>[dialogs.py]"]
end

subgraph group_setup["Receiver setup"]
  node_config["Receiver configuration<br/>[config.py]"]
  node_dependencies["Dependency setup<br/>[dependencies.py]"]
  node_usb["USB receiver setup<br/>[usb.py]"]
  node_sdr["SDR receiver setup<br/>[sdr.py]"]
  node_satip["Sat-IP setup<br/>[satip.py]"]
  node_standalone["Standalone setup<br/>[standalone.py]"]
  node_bitcoin["Bitcoin node support<br/>[bitcoin.py]"]
end

subgraph group_receive["Reception and monitoring"]
  node_rxmonitor["Receiver monitoring<br/>[monitoring.py]"]
  node_monitorapi["Monitoring service client<br/>[monitoring_api.py]"]
end

subgraph group_satapi["Satellite API"]
  node_satapi_cli["API command handlers<br/>[api.py]"]
  node_orders["Transmission orders<br/>[order.py]"]
  node_messages["Message encoding<br/>[msg.py]"]
  node_gpg["Message encryption<br/>[gpg.py]"]
  node_packet["Packet handling<br/>[pkt.py]"]
  node_satapi_gui["API GUI actions<br/>[api.py]"]
end

node_user(("Operator"))
node_satellite(("Satellite network"))
node_api_service(("Satellite API service"))
node_lightning(("Lightning Network"))
node_bitcoin_app(("Bitcoin Satellite app"))

node_user -->|"runs commands"| node_cli
node_user -->|"uses interface"| node_gui
node_cli -->|"dispatches setup"| node_config
node_cli -->|"dispatches setup"| node_dependencies
node_cli -->|"dispatches setup"| node_usb
node_cli -->|"dispatches setup"| node_sdr
node_cli -->|"dispatches setup"| node_satip
node_cli -->|"dispatches setup"| node_standalone
node_cli -->|"dispatches commands"| node_bitcoin
node_cli -->|"dispatches commands"| node_satapi_cli
node_gui -->|"opens window"| node_guiwindow
node_rxdashboard -->|"uses configuration"| node_config
node_rxdashboard -->|"uses setup"| node_dependencies
node_rxdashboard -->|"uses monitoring"| node_rxmonitor
node_guiwindow -.->|"presents receiver"| node_rxdashboard
node_satapi_gui -->|"uses API logic"| node_satapi_cli
node_satapidialogs -->|"uses API actions"| node_satapi_gui
node_satapi_cli -->|"manages orders"| node_orders
node_satapi_cli -->|"handles messages"| node_messages
node_satapi_cli -->|"uses encryption"| node_gpg
node_satapi_cli -->|"uses packets"| node_packet
node_orders -->|"sends requests"| node_api_service
node_satapi_cli -->|"monitoring commands"| node_monitorapi
node_rxmonitor -->|"uses service client"| node_monitorapi
node_usb -.->|"configures reception"| node_satellite
node_bitcoin_app -->|"receives broadcasts"| node_satellite
node_api_service -->|"broadcasts messages"| node_satellite
node_api_service -->|"accepts transmission payment"| node_lightning

click node_cli "https://github.com/blockstream/satellite/blob/master/blocksatcli/main.py"
click node_gui "https://github.com/blockstream/satellite/blob/master/blocksatgui/main.py"
click node_guiwindow "https://github.com/blockstream/satellite/blob/master/blocksatgui/mainwindow.py"
click node_rxdashboard "https://github.com/blockstream/satellite/blob/master/blocksatgui/receiver/dashboard.py"
click node_satapidialogs "https://github.com/blockstream/satellite/blob/master/blocksatgui/satapi/dialogs.py"
click node_config "https://github.com/blockstream/satellite/blob/master/blocksatcli/config.py"
click node_dependencies "https://github.com/blockstream/satellite/blob/master/blocksatcli/dependencies.py"
click node_usb "https://github.com/blockstream/satellite/blob/master/blocksatcli/usb.py"
click node_sdr "https://github.com/blockstream/satellite/blob/master/blocksatcli/sdr.py"
click node_satip "https://github.com/blockstream/satellite/blob/master/blocksatcli/satip.py"
click node_standalone "https://github.com/blockstream/satellite/blob/master/blocksatcli/standalone.py"
click node_bitcoin "https://github.com/blockstream/satellite/blob/master/blocksatcli/bitcoin.py"
click node_rxmonitor "https://github.com/blockstream/satellite/blob/master/blocksatcli/monitoring.py"
click node_monitorapi "https://github.com/blockstream/satellite/blob/master/blocksatcli/monitoring_api.py"
click node_satapi_cli "https://github.com/blockstream/satellite/blob/master/blocksatcli/api/api.py"
click node_orders "https://github.com/blockstream/satellite/blob/master/blocksatcli/api/order.py"
click node_messages "https://github.com/blockstream/satellite/blob/master/blocksatcli/api/msg.py"
click node_gpg "https://github.com/blockstream/satellite/blob/master/blocksatcli/api/gpg.py"
click node_packet "https://github.com/blockstream/satellite/blob/master/blocksatcli/api/pkt.py"
click node_satapi_gui "https://github.com/blockstream/satellite/blob/master/blocksatgui/satapi/api.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_cli,node_gui,node_guiwindow,node_rxdashboard,node_satapidialogs toneBlue
class node_config,node_dependencies,node_usb,node_sdr,node_satip,node_standalone,node_bitcoin toneAmber
class node_rxmonitor,node_monitorapi,node_api_service toneMint
class node_satapi_cli,node_orders,node_messages,node_gpg,node_packet,node_satapi_gui toneRose
class node_user,node_satellite,node_lightning,node_bitcoin_app toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/blockstream/satellite/blob/master/blocksatcli/main.py): `blocksatcli/main.py`
- [GUI application](https://github.com/blockstream/satellite/blob/master/blocksatgui/main.py): `blocksatgui/main.py`
- [Main window](https://github.com/blockstream/satellite/blob/master/blocksatgui/mainwindow.py): `blocksatgui/mainwindow.py`
- [Receiver dashboard](https://github.com/blockstream/satellite/blob/master/blocksatgui/receiver/dashboard.py): `blocksatgui/receiver/dashboard.py`
- [API dialogs](https://github.com/blockstream/satellite/blob/master/blocksatgui/satapi/dialogs.py): `blocksatgui/satapi/dialogs.py`

### Receiver setup

- [Receiver configuration](https://github.com/blockstream/satellite/blob/master/blocksatcli/config.py): `blocksatcli/config.py`
- [Dependency setup](https://github.com/blockstream/satellite/blob/master/blocksatcli/dependencies.py): `blocksatcli/dependencies.py`
- [USB receiver setup](https://github.com/blockstream/satellite/blob/master/blocksatcli/usb.py): `blocksatcli/usb.py`
- [SDR receiver setup](https://github.com/blockstream/satellite/blob/master/blocksatcli/sdr.py): `blocksatcli/sdr.py`
- [Sat-IP setup](https://github.com/blockstream/satellite/blob/master/blocksatcli/satip.py): `blocksatcli/satip.py`
- [Standalone setup](https://github.com/blockstream/satellite/blob/master/blocksatcli/standalone.py): `blocksatcli/standalone.py`
- [Bitcoin node support](https://github.com/blockstream/satellite/blob/master/blocksatcli/bitcoin.py): `blocksatcli/bitcoin.py`

### Reception and monitoring

- [Receiver monitoring](https://github.com/blockstream/satellite/blob/master/blocksatcli/monitoring.py): `blocksatcli/monitoring.py`
- [Monitoring service client](https://github.com/blockstream/satellite/blob/master/blocksatcli/monitoring_api.py): `blocksatcli/monitoring_api.py`

### Satellite API

- [API command handlers](https://github.com/blockstream/satellite/blob/master/blocksatcli/api/api.py): `blocksatcli/api/api.py`
- [Transmission orders](https://github.com/blockstream/satellite/blob/master/blocksatcli/api/order.py): `blocksatcli/api/order.py`
- [Message encoding](https://github.com/blockstream/satellite/blob/master/blocksatcli/api/msg.py): `blocksatcli/api/msg.py`
- [Message encryption](https://github.com/blockstream/satellite/blob/master/blocksatcli/api/gpg.py): `blocksatcli/api/gpg.py`
- [Packet handling](https://github.com/blockstream/satellite/blob/master/blocksatcli/api/pkt.py): `blocksatcli/api/pkt.py`
- [API GUI actions](https://github.com/blockstream/satellite/blob/master/blocksatgui/satapi/api.py): `blocksatgui/satapi/api.py`

### Other components

- **Operator**
- **Satellite network**
- **Satellite API service**
- **Lightning Network**
- **Bitcoin Satellite app**

## Connections

- Operator → CLI commands: runs commands (evidence: `README.md`)
- Operator → GUI application: uses interface (evidence: `README.md`)
- CLI commands → Receiver configuration: dispatches setup (evidence: `blocksatcli/main.py`)
- CLI commands → Dependency setup: dispatches setup (evidence: `blocksatcli/main.py`)
- CLI commands → USB receiver setup: dispatches setup (evidence: `blocksatcli/main.py`)
- CLI commands → SDR receiver setup: dispatches setup (evidence: `blocksatcli/main.py`)
- CLI commands → Sat-IP setup: dispatches setup (evidence: `blocksatcli/main.py`)
- CLI commands → Standalone setup: dispatches setup (evidence: `blocksatcli/main.py`)
- CLI commands → Bitcoin node support: dispatches commands (evidence: `blocksatcli/main.py`)
- CLI commands → API command handlers: dispatches commands (evidence: `blocksatcli/main.py`)
- GUI application → Main window: opens window
- Receiver dashboard → Receiver configuration: uses configuration (evidence: `blocksatgui/receiver/dashboard.py`)
- Receiver dashboard → Dependency setup: uses setup (evidence: `blocksatgui/receiver/dashboard.py`)
- Receiver dashboard → Receiver monitoring: uses monitoring (evidence: `blocksatgui/receiver/dashboard.py`)
- Main window → Receiver dashboard: presents receiver
- API GUI actions → API command handlers: uses API logic (evidence: `blocksatgui/satapi/api.py`)
- API dialogs → API GUI actions: uses API actions (evidence: `blocksatgui/satapi/dialogs.py`)
- API command handlers → Transmission orders: manages orders (evidence: `blocksatcli/api/api.py`)
- API command handlers → Message encoding: handles messages (evidence: `blocksatcli/api/api.py`)
- API command handlers → Message encryption: uses encryption (evidence: `blocksatcli/api/api.py`)
- API command handlers → Packet handling: uses packets (evidence: `blocksatcli/api/api.py`)
- Transmission orders → Satellite API service: sends requests (evidence: `blocksatcli/api/order.py`)
- API command handlers → Monitoring service client: monitoring commands (evidence: `blocksatcli/main.py`)
- Receiver monitoring → Monitoring service client: uses service client (evidence: `blocksatcli/monitoring.py`)
- USB receiver setup → Satellite network: configures reception
- Bitcoin Satellite app → Satellite network: receives broadcasts (evidence: `README.md`)
- Satellite API service → Satellite network: broadcasts messages (evidence: `README.md`)
- Satellite API service → Lightning Network: accepts transmission payment (evidence: `README.md`)
