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/*.confis receiver inventory./etc/rfsentry/routes.d/*.confis 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.