# haohanhe/mbdsdr architecture

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

- Interactive diagram: https://gitdiagram.com/haohanhe/mbdsdr
- Repository: https://github.com/haohanhe/mbdsdr

## Overview

MBDSDR is an AI-operated SDR and measurement system spanning a native C++ desktop, a mobile companion, and a Python research kernel. The main workflow is an external agent connecting over MCP, invoking tools to control real radio/VNA hardware, and retrieving measured signal, decode, or sweep results; write operations are gated for human approval. The graph also preserves receiving/decoding, satellite processing, and the desktop HTTP control path. Source excerpts are partial, so some subsystem links are documented by the README rather than inferred from unsampled implementation.

Main entry points: [`cpp/src/dsp/spectrum_engine.cpp`](https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/dsp/spectrum_engine.cpp) (Spectrum engine), [`mbdsdr_ai/sat_pipeline_runner.py`](https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/sat_pipeline_runner.py) (Satellite pipeline runner), [`cpp/src/vna/nanovna_client.cpp`](https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/vna/nanovna_client.cpp) (NanoVNA client), [`mbdsdr_ai/core/controller.py`](https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/core/controller.py) (Python controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Agent Control"]
  node_mcp["MCP server<br/>[mcp_server.cpp]"]
  node_ai_tools["AI tool surface<br/>[agent_tools.cpp]"]
  node_llm_worker["LLM worker<br/>[llm_worker.cpp]"]
  node_llm_client["LLM transport<br/>[llm_client.cpp]"]
  node_control_hub["HTTP control hub<br/>[control_hub.cpp]"]
  node_http_server["Control HTTP server"]
  node_mobile["Mobile companion<br/>[MainActivity.kt]"]
end

subgraph group_radio["Radio Runtime"]
  node_spectrum_engine["Spectrum engine"]
  node_radio_source["SDR source backends<br/>[rtl_sdr_source.cpp]"]
  node_demod["Demodulation<br/>[demod.cpp]"]
  node_spectrum["Spectrum analysis<br/>[power_spectrum.cpp]"]
  node_decoder["Protocol decoding<br/>[adsb_decoder.cpp]"]
end

subgraph group_measurement["VNA Measurement"]
  node_vna_client["NanoVNA client<br/>[nanovna_client.cpp]"]
  node_vna_analysis["VNA analysis<br/>[vna_pipeline.py]"]
end

subgraph group_satellite["Satellite Processing"]
  node_sat_params["Satellite pipeline registry"]
  node_sat_runner["Satellite pipeline runner"]
  node_sat_demod["Satellite demodulation<br/>[meteor_sat.py]"]
  node_sat_images["Satellite image decoding<br/>[gk2a_lrit.py]"]
end

subgraph group_python["Python Kernel"]
  node_py_controller["Python controller<br/>[controller.py]"]
  node_py_workflows["Workflow engine<br/>[workflow_engine.py]"]
  node_web_server["Python web control<br/>[server.py]"]
end

node_agent(("External AI agent"))
node_hardware["SDR / VNA hardware"]

node_agent -->|"controls via MCP"| node_mcp
node_mcp -.->|"dispatches tools"| node_ai_tools
node_ai_tools -->|"controls radio"| node_spectrum_engine
node_llm_worker -->|"sends chat requests"| node_llm_client
node_llm_client -.->|"calls model API"| node_agent
node_mobile -->|"reads via HTTP"| node_http_server
node_http_server -.->|"routes controls"| node_control_hub
node_control_hub -->|"controls engine"| node_spectrum_engine
node_spectrum_engine -->|"reads IQ"| node_radio_source
node_radio_source -->|"receives samples"| node_hardware
node_spectrum_engine -->|"computes spectrum"| node_spectrum
node_spectrum_engine -->|"demodulates signals"| node_demod
node_spectrum_engine -->|"decodes protocols"| node_decoder
node_spectrum_engine -->|"exposes VNA access"| node_vna_client
node_vna_client -->|"measures RF"| node_hardware
node_vna_analysis -.->|"analyzes sweep data"| node_vna_client
node_py_controller -.->|"runs workflows"| node_py_workflows
node_py_controller -.->|"serves controls"| node_web_server
node_sat_runner -->|"uses stage registry"| node_sat_params
node_sat_runner -->|"dispatches demodulation"| node_sat_demod
node_sat_runner -->|"dispatches image decoding"| node_sat_images

click node_mcp "https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/agentapi/mcp_server.cpp"
click node_ai_tools "https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/ai/agent_tools.cpp"
click node_llm_worker "https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/ai/llm_worker.cpp"
click node_llm_client "https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/ai/llm_client.cpp"
click node_control_hub "https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/control/control_hub.cpp"
click node_http_server "https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/control/control_http_server.cpp"
click node_mobile "https://github.com/haohanhe/mbdsdr/blob/main/mobile/android/app/src/main/kotlin/mbdsdr/app/MainActivity.kt"
click node_spectrum_engine "https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/dsp/spectrum_engine.cpp"
click node_radio_source "https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/dsp/rtl_sdr_source.cpp"
click node_demod "https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/dsp/demod.cpp"
click node_spectrum "https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/dsp/power_spectrum.cpp"
click node_decoder "https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/dsp/adsb_decoder.cpp"
click node_vna_client "https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/vna/nanovna_client.cpp"
click node_vna_analysis "https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/vna_pipeline.py"
click node_sat_params "https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/sat_pipeline_params.py"
click node_sat_runner "https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/sat_pipeline_runner.py"
click node_sat_demod "https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/meteor_sat.py"
click node_sat_images "https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/gk2a_lrit.py"
click node_py_controller "https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/core/controller.py"
click node_py_workflows "https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/workflow_engine.py"
click node_web_server "https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/web/server.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_mcp,node_ai_tools,node_llm_worker,node_llm_client,node_control_hub,node_http_server,node_mobile toneBlue
class node_spectrum_engine,node_radio_source,node_demod,node_spectrum,node_decoder toneAmber
class node_vna_client,node_vna_analysis toneMint
class node_sat_params,node_sat_runner,node_sat_demod,node_sat_images toneRose
class node_py_controller,node_py_workflows,node_web_server,node_agent,node_hardware toneIndigo
```

## Components

### Agent Control

- [MCP server](https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/agentapi/mcp_server.cpp): `cpp/src/agentapi/mcp_server.cpp`
- [AI tool surface](https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/ai/agent_tools.cpp): `cpp/src/ai/agent_tools.cpp`
- [LLM worker](https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/ai/llm_worker.cpp): `cpp/src/ai/llm_worker.cpp`
- [LLM transport](https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/ai/llm_client.cpp): `cpp/src/ai/llm_client.cpp`
- [HTTP control hub](https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/control/control_hub.cpp): `cpp/src/control/control_hub.cpp`
- [Control HTTP server](https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/control/control_http_server.cpp): `cpp/src/control/control_http_server.cpp`
- [Mobile companion](https://github.com/haohanhe/mbdsdr/blob/main/mobile/android/app/src/main/kotlin/mbdsdr/app/MainActivity.kt): `mobile/android/app/src/main/kotlin/mbdsdr/app/MainActivity.kt`

### Radio Runtime

- [Spectrum engine](https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/dsp/spectrum_engine.cpp): `cpp/src/dsp/spectrum_engine.cpp`
- [SDR source backends](https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/dsp/rtl_sdr_source.cpp): `cpp/src/dsp/rtl_sdr_source.cpp`
- [Demodulation](https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/dsp/demod.cpp): `cpp/src/dsp/demod.cpp`
- [Spectrum analysis](https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/dsp/power_spectrum.cpp): `cpp/src/dsp/power_spectrum.cpp`
- [Protocol decoding](https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/dsp/adsb_decoder.cpp): `cpp/src/dsp/adsb_decoder.cpp`

### VNA Measurement

- [NanoVNA client](https://github.com/haohanhe/mbdsdr/blob/main/cpp/src/vna/nanovna_client.cpp): `cpp/src/vna/nanovna_client.cpp`
- [VNA analysis](https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/vna_pipeline.py): `mbdsdr_ai/vna_pipeline.py`

### Satellite Processing

- [Satellite pipeline registry](https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/sat_pipeline_params.py): `mbdsdr_ai/sat_pipeline_params.py`
- [Satellite pipeline runner](https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/sat_pipeline_runner.py): `mbdsdr_ai/sat_pipeline_runner.py`
- [Satellite demodulation](https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/meteor_sat.py): `mbdsdr_ai/meteor_sat.py`
- [Satellite image decoding](https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/gk2a_lrit.py): `mbdsdr_ai/gk2a_lrit.py`

### Python Kernel

- [Python controller](https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/core/controller.py): `mbdsdr_ai/core/controller.py`
- [Workflow engine](https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/workflow_engine.py): `mbdsdr_ai/workflow_engine.py`
- [Python web control](https://github.com/haohanhe/mbdsdr/blob/main/mbdsdr_ai/web/server.py): `mbdsdr_ai/web/server.py`

### Other components

- **External AI agent**
- **SDR / VNA hardware**

## Connections

- External AI agent → MCP server: controls via MCP (evidence: `README.md`)
- MCP server → AI tool surface: dispatches tools
- AI tool surface → Spectrum engine: controls radio (evidence: `README.md`)
- LLM worker → LLM transport: sends chat requests (evidence: `cpp/src/ai/llm_worker.cpp`)
- LLM transport → External AI agent: calls model API
- Mobile companion → Control HTTP server: reads via HTTP (evidence: `README.md`)
- Control HTTP server → HTTP control hub: routes controls
- HTTP control hub → Spectrum engine: controls engine (evidence: `README.md`)
- Spectrum engine → SDR source backends: reads IQ (evidence: `cpp/src/dsp/spectrum_engine.cpp`)
- SDR source backends → SDR / VNA hardware: receives samples (evidence: `README.md`)
- Spectrum engine → Spectrum analysis: computes spectrum (evidence: `cpp/src/dsp/spectrum_engine.cpp`)
- Spectrum engine → Demodulation: demodulates signals
- Spectrum engine → Protocol decoding: decodes protocols (evidence: `cpp/src/dsp/spectrum_engine.cpp`)
- Spectrum engine → NanoVNA client: exposes VNA access
- NanoVNA client → SDR / VNA hardware: measures RF (evidence: `README.md`)
- VNA analysis → NanoVNA client: analyzes sweep data
- Python controller → Workflow engine: runs workflows
- Python controller → Python web control: serves controls (evidence: `mbdsdr_ai/core/controller.py`)
- Satellite pipeline runner → Satellite pipeline registry: uses stage registry (evidence: `mbdsdr_ai/sat_pipeline_runner.py`)
- Satellite pipeline runner → Satellite demodulation: dispatches demodulation (evidence: `mbdsdr_ai/sat_pipeline_runner.py`)
- Satellite pipeline runner → Satellite image decoding: dispatches image decoding (evidence: `mbdsdr_ai/sat_pipeline_runner.py`)