# cbassa/strf architecture

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

- Interactive diagram: https://gitdiagram.com/cbassa/strf
- Repository: https://github.com/cbassa/strf

## Overview

#### Purpose and execution model
STRF is a native Linux satellite-radio tracking toolkit. It converts SDR I/Q streams into timestamped spectrograms, then supports Doppler-curve visualization, satellite identification, orbit fitting, and trace analysis. It is a collection of C command-line executables rather than a server or web application. Build/install entry points are `makefile`, `Makefile.linux`, and `Makefile.osx`; operational setup and command usage are in `README.md`.

#### Acquisition and spectrogram production
`rffft.c` is the primary ingestion entry point. It accepts complex I/Q from files, stdin pipelines, or FIFOs connected to SDR software, supports several sample encodings, and produces `.bin` waterfall/spectrogram artifacts. The FFT implementation is split between `rffft.c`, `rffft_internal.c`, and `rffft_internal.h`. This is the key boundary between external SDR/device tools (RTL-SDR, HackRF, Airspy, GNU Radio, Pluto/IIO) and STRF’s stable binary analysis format.

#### Spectrogram artifact format and I/O
The generated artifact begins with a human-readable fixed header followed by floating-point spectral-power samples. Shared parsing and serialization facilities are centralized in `rfio.c` and `rfio.h`; image export is handled by `rfpng.c`. Downstream tools consume these files rather than raw SDR streams, allowing acquisition and analysis to run separately. Python utilities in `contrib/`, notably `contrib/spectrum_parser.py` and `contrib/analyze_artifact.py`, provide auxiliary artifact inspection and analysis outside the C command suite.

#### Analysis and visualization commands
`rfplot.c` is the principal visualization entry point for waterfall plots and analysis of generated spectra. Related command programs provide focused processing stages: `rfedit.c` for editing spectral data, `rffind.c` for detection/identification workflows, `rftrace.c` for Doppler-trace handling, and `rffit.c` for fitting. `rfinfo.c` exposes artifact metadata. These tools form a file-oriented analysis pipeline around the `.bin` output rather than sharing a long-running process.

#### Orbital prediction, TLE, and site domain model
Satellite propagation and observation geometry are built around SGP4 and Two-Line Element data: `sgdp4.c`, `sgdp4h.h`, `rftles.c`, and `rftles.h`. Station/site lookup is represented by `rfsites.c` and `rfsites.h`, with default reference data in `data/sites.txt`; frequency reference data resides in `data/frequencies.txt`. `rfdop.c` calculates Doppler-related behavior, connecting predicted orbital motion to measured spectral traces.

#### TLE refresh and external services
The `tleupdate` executable/script is the TLE acquisition entry point. It depends on configured environment variables including `ST_TLEDIR`, site identity, and Space-Track credentials (`ST_LOGIN`), making Space-Track an important external service boundary. Satellite prediction and fitting operate on locally stored TLE files after retrieval, avoiding a runtime dependency on the remote service during normal analysis.

#### Native dependencies and quality boundary
The C toolchain links material scientific and graphics dependencies: FFTW for FFTs, GSL for numerical work, PGPLOT/X11 for plotting, libpng for image output, and SoX/WAV support for recordings. Numerical fitting support is represented by `simplex.c`, `versafit.c`, and `deep.c`. Unit tests target core binary, FFT, and TLE behavior under CMocka in `tests/tests.c`, `tests/tests_rfio.c`, and `tests/tests_rftles.c`.

Main entry points: [`rffft.c`](https://github.com/cbassa/strf/blob/main/rffft.c) (rffft), [`rfedit.c`](https://github.com/cbassa/strf/blob/main/rfedit.c) (Edit, find, trace & fit), [`rfdop.c`](https://github.com/cbassa/strf/blob/main/rfdop.c) (Doppler calculation), [`makefile`](https://github.com/cbassa/strf/blob/main/makefile) (Native build entry points)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Acquisition"]
  node_rffft["rffft<br/>CLI acquisition<br/>[rffft.c]"]
  node_fft["FFT implementation<br/>signal-processing core<br/>[rffft_internal.c]"]
end

subgraph group_artifact["Artifact Pipeline"]
  node_spectrogram[(".bin spectrogram<br/>binary artifact")]
  node_rfio["rfio<br/>artifact I/O<br/>[rfio.c]"]
  node_rfplot["rfplot<br/>visualization CLI<br/>[rfplot.c]"]
  node_rfpng["rfpng<br/>image export<br/>[rfpng.c]"]
  node_analysis_clis["Edit, find, trace &amp; fit<br/>analysis CLIs<br/>[rfedit.c]"]
  node_rfinfo["rfinfo<br/>metadata CLI<br/>[rfinfo.c]"]
  node_python_tools["Python artifact utilities<br/>auxiliary analysis"]
end

subgraph group_orbit["Orbit &amp; Doppler"]
  node_tleupdate["tleupdate<br/>TLE refresh CLI"]
  node_tle_store[("Local TLE files<br/>orbital data")]
  node_propagation["SGP4 &amp; TLE model<br/>orbital propagation<br/>[sgdp4.c]"]
  node_sites["Site model<br/>observation geometry<br/>[rfsites.c]"]
  node_site_data["Site &amp; frequency data<br/>reference data<br/>[sites.txt]"]
  node_doppler["Doppler calculation<br/>prediction core<br/>[rfdop.c]"]
  node_numerics["Fitting numerics<br/>numerical core<br/>[simplex.c]"]
end

subgraph group_external["External Boundaries"]
  node_sdr{{"SDR tools &amp; I/Q sources<br/>external input"}}
  node_fftw{{"FFTW<br/>native dependency"}}
  node_spacetrack{{"Space-Track<br/>external service"}}
end

node_build["Native build entry points"]

node_build -->|"builds"| node_rffft
node_build -->|"builds"| node_analysis_clis
node_sdr -->|"I/Q stream"| node_rffft
node_rffft -->|"computes spectra"| node_fft
node_fftw -->|"FFT library"| node_fft
node_rffft -->|"writes"| node_spectrogram
node_rfio -->|"parses and serializes"| node_spectrogram
node_spectrogram -->|"visualizes"| node_rfplot
node_rfplot -->|"exports image"| node_rfpng
node_spectrogram -->|"analysis input"| node_analysis_clis
node_spectrogram -->|"metadata input"| node_rfinfo
node_spectrogram -->|"auxiliary inspection"| node_python_tools
node_spacetrack -->|"retrieves from"| node_tleupdate
node_tleupdate -->|"updates"| node_tle_store
node_tle_store -->|"TLE input"| node_propagation
node_site_data -->|"reference data"| node_sites
node_propagation -->|"predicted motion"| node_doppler
node_sites -->|"observer geometry"| node_doppler
node_doppler -->|"trace prediction and fitting"| node_analysis_clis
node_numerics -->|"fit support"| node_analysis_clis

click node_build "https://github.com/cbassa/strf/blob/main/makefile"
click node_rffft "https://github.com/cbassa/strf/blob/main/rffft.c"
click node_fft "https://github.com/cbassa/strf/blob/main/rffft_internal.c"
click node_rfio "https://github.com/cbassa/strf/blob/main/rfio.c"
click node_rfplot "https://github.com/cbassa/strf/blob/main/rfplot.c"
click node_rfpng "https://github.com/cbassa/strf/blob/main/rfpng.c"
click node_analysis_clis "https://github.com/cbassa/strf/blob/main/rfedit.c"
click node_rfinfo "https://github.com/cbassa/strf/blob/main/rfinfo.c"
click node_python_tools "https://github.com/cbassa/strf/blob/main/contrib/analyze_artifact.py"
click node_tleupdate "https://github.com/cbassa/strf/blob/main/tleupdate"
click node_propagation "https://github.com/cbassa/strf/blob/main/sgdp4.c"
click node_sites "https://github.com/cbassa/strf/blob/main/rfsites.c"
click node_site_data "https://github.com/cbassa/strf/blob/main/data/sites.txt"
click node_doppler "https://github.com/cbassa/strf/blob/main/rfdop.c"
click node_numerics "https://github.com/cbassa/strf/blob/main/simplex.c"

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_rffft,node_fft toneBlue
class node_spectrogram,node_rfio,node_rfplot,node_rfpng,node_analysis_clis,node_rfinfo,node_python_tools toneAmber
class node_tleupdate,node_tle_store,node_propagation,node_sites,node_site_data,node_doppler,node_numerics toneMint
class node_sdr,node_fftw,node_spacetrack toneRose
class node_build toneNeutral
```

## Components

### Acquisition

Raw SDR input to spectrogram production.

- [rffft](https://github.com/cbassa/strf/blob/main/rffft.c): CLI acquisition · Ingests files, stdin, or FIFOs and generates spectral data. · `rffft.c`
- [FFT implementation](https://github.com/cbassa/strf/blob/main/rffft_internal.c): signal-processing core · `rffft_internal.c`

### Artifact Pipeline

File-oriented spectrogram inspection and analysis.

- **.bin spectrogram**: binary artifact · Fixed text header followed by floating-point spectral-power samples.
- [rfio](https://github.com/cbassa/strf/blob/main/rfio.c): artifact I/O · Shared parsing and serialization for spectrogram files. · `rfio.c`
- [rfplot](https://github.com/cbassa/strf/blob/main/rfplot.c): visualization CLI · Produces waterfall plots and spectrum analysis. · `rfplot.c`
- [rfpng](https://github.com/cbassa/strf/blob/main/rfpng.c): image export · `rfpng.c`
- [Edit, find, trace & fit](https://github.com/cbassa/strf/blob/main/rfedit.c): analysis CLIs · Focused file-oriented processing commands. · `rfedit.c`
- [rfinfo](https://github.com/cbassa/strf/blob/main/rfinfo.c): metadata CLI · `rfinfo.c`
- [Python artifact utilities](https://github.com/cbassa/strf/blob/main/contrib/analyze_artifact.py): auxiliary analysis · `contrib/analyze_artifact.py`

### Orbit & Doppler

Satellite, site, and fitting domain model.

- [tleupdate](https://github.com/cbassa/strf/blob/main/tleupdate): TLE refresh CLI · Retrieves TLEs into local storage using configured credentials. · `tleupdate`
- **Local TLE files**: orbital data · Allows normal analysis without remote service access.
- [SGP4 & TLE model](https://github.com/cbassa/strf/blob/main/sgdp4.c): orbital propagation · `sgdp4.c`
- [Site model](https://github.com/cbassa/strf/blob/main/rfsites.c): observation geometry · Station lookup uses bundled reference sites. · `rfsites.c`
- [Site & frequency data](https://github.com/cbassa/strf/blob/main/data/sites.txt): reference data · `data/sites.txt`
- [Doppler calculation](https://github.com/cbassa/strf/blob/main/rfdop.c): prediction core · Connects orbital motion with measured spectral traces. · `rfdop.c`
- [Fitting numerics](https://github.com/cbassa/strf/blob/main/simplex.c): numerical core · `simplex.c`

### External Boundaries

Device, service, and native dependency boundaries.

- **SDR tools & I/Q sources**: external input · RTL-SDR, HackRF, Airspy, GNU Radio, and Pluto/IIO provide streams.
- **FFTW**: native dependency
- **Space-Track**: external service · Credentialed source for refreshed TLE data.

### Other components

- [Native build entry points](https://github.com/cbassa/strf/blob/main/makefile): build · `makefile`

## Connections

- Native build entry points → rffft: builds
- Native build entry points → Edit, find, trace & fit: builds
- SDR tools & I/Q sources → rffft: I/Q stream
- rffft → FFT implementation: computes spectra
- FFTW → FFT implementation: FFT library
- rffft → .bin spectrogram: writes
- rfio → .bin spectrogram: parses and serializes
- .bin spectrogram → rfplot: visualizes
- rfplot → rfpng: exports image
- .bin spectrogram → Edit, find, trace & fit: analysis input
- .bin spectrogram → rfinfo: metadata input
- .bin spectrogram → Python artifact utilities: auxiliary inspection
- Space-Track → tleupdate: retrieves from
- tleupdate → Local TLE files: updates
- Local TLE files → SGP4 & TLE model: TLE input
- Site & frequency data → Site model: reference data
- SGP4 & TLE model → Doppler calculation: predicted motion
- Site model → Doppler calculation: observer geometry
- Doppler calculation → Edit, find, trace & fit: trace prediction and fitting
- Fitting numerics → Edit, find, trace & fit: fit support