# karlcswanson/spectrum-capture architecture

> Architecture diagram of the GitHub repository karlcswanson/spectrum-capture, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karlcswanson/spectrum-capture
- Repository: https://github.com/karlcswanson/spectrum-capture

## Overview

##### Recognize the Project’s Nature and Purpose
- This project is a standalone Go application that acts as a wrapper around external utilities (like soapy_power) to capture spectrum scan data and stream it to an MQTT broker.
- Its main function is to take configuration input (via an environment variable), invoke external commands that output rtl_power–formatted data, parse that data, and then publish incremental and complete scan details to an MQTT broker.

##### Main Components
a. Configuration Loader:
– Reads the SPECTRUM_CFG JSON (provided via the environment) that includes parameters such as name, description, command, and server details.
b. Command Execution Module (Embedded in main.go):
– Responsible for invoking the external process (soapy_power or similar utilities) and capturing its output over stdio.
c. Data Parsing and Handling Component:
– Processes the streamed output (stdout) from the external command and prepares data (both incremental and complete scans) for transmission.
d. MQTT Manager (mqtt_manager.go):
– Manages the connection to the MQTT broker and takes care of the publishing of scan data.
e. Deployment/Build Tool:
– Though not part of the runtime architecture, deploy.sh indicates remote deployment capability (cross-compilation for arm64 and remote startup) that can be annotated as part of the build/deployment pipeline.

##### Mapping Relationships and Interactions
- The Configuration component feeds settings (including command and MQTT server details) into the main process.
- The main process uses these settings to execute the external utility (soapy_power) and receive standard output.
- The Data Parsing component converts this raw output into a format suitable for the MQTT Manager.
- The MQTT Manager connects to the MQTT broker as defined in the configuration and streams the processed scan data.
- That the deploy.sh script is used to compile and deploy the binary to a remote device where it runs, ensuring that the containerized soapySDR environment is utilized.

##### Architectural Patterns and Key Technologies
- The system is built around a simple pipeline: configuration → execution (of an external command) → data parsing → message publishing.
- Modularity with clear separation between configuration, command execution, data parsing, and MQTT communication.
- The usage of MQTT messaging for data streaming is an important architectural point.
- Go’s native modules (go.mod, go.sum) underline dependency management and language-specific patterns.

[Configuration Loader] → [Command Executor] → [Data Parser] → [MQTT Manager] → [MQTT Broker]

## Diagram (Mermaid)

```mermaid
flowchart TD
    deploy["Deployment Pipeline (deploy.sh)"]:::deployment
    deploy -->|"deploys binary"| conf["Configuration Loader (SPECTRUM_CFG)"]:::configuration

    subgraph "Spectrum Capture Application"
        conf
        cmd["Command Executor (soapy_power invocation)"]:::execution
        parser["Data Parser & Handler"]:::dataParser
        mqttM["MQTT Manager"]:::mqtt

        conf -->|"feeds config"| cmd
        conf -->|"provides settings"| mqttM
        cmd -->|"STDOUT data"| parser
        parser -->|"parsed data"| mqttM
    end

    mqttM -->|"publishes scan data"| broker["External MQTT Broker"]:::external

    click deploy "https://github.com/karlcswanson/spectrum-capture/blob/main/deploy.sh"
    click conf "https://github.com/karlcswanson/spectrum-capture/blob/main/main.go"
    click cmd "https://github.com/karlcswanson/spectrum-capture/blob/main/main.go"
    click parser "https://github.com/karlcswanson/spectrum-capture/blob/main/main.go"
    click mqttM "https://github.com/karlcswanson/spectrum-capture/blob/main/mqtt_manager.go"

    classDef configuration fill:#b3e6ff,stroke:#333,stroke-width:2px;
    classDef execution fill:#ffd699,stroke:#333,stroke-width:2px;
    classDef dataParser fill:#ffff99,stroke:#333,stroke-width:2px;
    classDef mqtt fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef external fill:#d9ead3,stroke:#333,stroke-width:2px;
    classDef deployment fill:#d0e0e3,stroke:#333,stroke-width:2px;
```
