Skip to content

End-to-end system architecture

The Pi runs the receiver. The workstation can listen to the resulting IQ stream, read decoded records from a continuous job on the Pi, or browse records and products on a paired Server. The system overview shows those paths together.

Interactive IQ path

Opening a lane on an idle receiver wakes it on demand. Browser DSP, decoder and replay workers receive independent feeds from that lane’s IQ stream.

flowchart TB
    subgraph RF[Physical RF]
      ANT[Antenna and configured RF path] --> RTL[RTL-SDR receiver]
    end
    subgraph PI[RF Sentry appliance]
      INV[Serial inventory and route policy]
      DEMAND[sdr-demandd]
      SUP[serial-aware rtl_tcp supervisor]
      API[rfsentry-api]
      UPD[local dataset updaters]
      INV -. receiver identity .-> DEMAND
      INV -. route selection .-> API
      UPD --> API
    end
    subgraph BROWSER[Workstation browser]
      CTRL[Lane and control state]
      IQ[IQ ingress worker]
      DSP[Realtime DSP workers]
      DET[Detection / candidate analysis]
      DEC[Decoder input and isolated decoder workers]
      INTEL[Intelligence / product workers]
      STORE[IndexedDB + OPFS]
      GPU[Canvas / WebGL / WebGPU presentation]
      CTRL --> IQ
      IQ --> DSP
      IQ --> DET
      IQ --> DEC
      DET -. selection evidence .-> DEC
      DEC --> INTEL
      IQ --> DVR[(Raw IQ replay in RAM / OPFS)]
      INTEL <--> STORE
      DSP --> GPU
      INTEL --> GPU
    end
    RTL --> SUP --> DEMAND --> API
    API == TLS WebSocket IQ ==> IQ
    CTRL == JSON control ==> API

Responsibility boundary

Appliance Browser/workstation
Receiver inventory by serial Lane ownership and operator state
Route eligibility and RF translation VFO, channelizer, demodulator, audio
Demand wake/sleep and USB topology Spectrum, waterfall, detector/classifier
rtl_tcp supervision Protocol decoder workers and WASM
TLS, origin/auth policy, WebSockets DVR hot/warm tiers and replay
Raw CU8 framing and source continuity Intelligence, archive, map, search
Atomic local reference datasets IndexedDB/OPFS hydration and caches

The gateway connects to the demand manager’s receiver port. It can also feed IQ to a continuous HRIT decoder on the Pi. That separate process returns decoded records to the gateway’s bounded RAM buffer. A browser can read the buffer directly. A paired Server can also subscribe, archive an enabled stream to disk and reconstruct supported GOES products when processing is enabled. See record sources for the choices in the browser.

Data and control planes

The JSON control WebSocket on configured API_PORT (default 8443; generated gateway key PORT) opens, tunes, configures, and closes lane sessions. The binary IQ WebSocket carries session-bound CU8 frames with sample counters, capture geometry, discontinuity flags, and time anchors. Control readiness can arrive before an open response is rendered, so the client buffers early events. After authentication, stream.endpoint advertises the dedicated external STREAM_PORT (default 8444) for IQ; each lane binds its session token on a separate WSS connection. Both listeners are in one gateway process and share TLS identity. There is no IQ fallback through the API listener. Appliance nftables priority applies to the dedicated IQ port, not UI/control/downloads.

The lane's raw evidence is fanned out through independent bounded worker paths. Decoder IQ comes from its own ingress sink, not serially through detection or candidate analysis; those supply selection evidence, and manual VFO decoding remains available with detection off. Realtime audio/control stay protected. The dedicated display FFT adapts independently of scientific analysis; the realtime 4,096-bin wide FFT is not a universal display or scientific-resolution limit. See browser DSP for the separate geometries. Optional work must yield or report local loss rather than backpressure acquisition without bounds.

Source-of-truth boundaries

  • /etc/rtl_tcp/*.conf is receiver inventory.
  • /etc/rfsentry/routes.d/*.conf is route and translation policy.
  • decoder manifests/catalog are decoder input and execution policy.
  • raw capture-time observations and received files are evidence.
  • map indexes, summaries and thumbnails can be rebuilt from retained source observations or product assets.
  • the Server acknowledges a record after its archive commit is durable. A browser download cursor tracks that browser’s progress separately.
  • browser presentation state is never authoritative protocol evidence.

Temporal model

flowchart TB
    RF[Sample counter + time anchor] --> OBS[Capture-time observation]
    OBS --> RAW[(Authoritative history)]
    RAW --> LIVE[Incremental current snapshot]
    RAW --> INDEX[Time/source indexes and checkpoints]
    INDEX --> QUERY[Latest-request-wins as-of query]
    LIVE --> NOW[Live UI and map]
    QUERY --> REPLAY[Historical UI and map]

Live state and historical/as-of state are intentionally separate. Live updates touch changed entities. Historical reconstruction is an explicit indexed worker query. A generation token prevents stale historical responses from mutating the active Live view after a mode change.

Continue reading