Candidate RF Sentry native local client roadmap¶
- Status: exploratory candidate; not approved for implementation
- Recorded: 2026-09-24
- Relationship to the web client: complementary, not a replacement mandate
Purpose¶
RF Sentry currently follows a thin-appliance, powerful-browser architecture. The Raspberry Pi acquires and transports IQ while the browser client owns most DSP, audio, decoding, history, station intelligence, geographic analysis, and operator presentation.
This document records a possible second client: an ultra-performance native local application with a C++ processing core. The existing web client would remain a supported, capable client rather than becoming disposable migration scaffolding.
The product could ultimately offer two peers:
| Client | Intended role |
|---|---|
| Web client | Installation-free remote access, broad portability, rapid UI delivery, and a lightweight but still powerful RF workstation |
| Native local client | Maximum sample rate, memory scale, DSP throughput, recording depth, decoder isolation, and workstation integration |
Both clients should consume the same appliance protocols and preserve the same RF, identity, capture-time, replay, and geographic semantics.
Feasibility assessment¶
A native C++ client is technically feasible. The RF-facing parts of the current browser application are particularly suitable for native execution:
- IQ transport, framing, continuity tracking, and backpressure
- long-duration raw-IQ DVR and durable recording
- multithreaded DSP, channelization, FFTs, demodulation, and detection
- SIMD and platform-specific acceleration
- audio buffering, mixing, device selection, and output
- decoder orchestration and process/module isolation
- native SQLite access for FCC, station, and investigative data
- explicit CPU affinity, thread priority, memory mapping, and diagnostics
- more predictable use of large workstation memory pools
A native client would not require the Pi to perform workstation DSP. The Pi should remain the lightweight, remotely recoverable acquisition appliance.
Candidate architecture¶
RF Sentry appliance
rtl-sdr / demand control / IQ gateway
|
| existing versioned control + IQ protocols
v
Native local client
C++ RF engine
- IQ ingress and segmented capture timeline
- DSP, demodulation, detection, and classification
- decoder orchestration and fault isolation
- audio engine
- DVR, recordings, and replay
- station/FCC/geographic data services
- GPU-ready presentation data
|
v
Qt Quick/QML operator interface
- spectrum, waterfall, VFO, and passband
- decoder and investigation workspaces
- station dossiers and search
- native window/layout management
- initially embedded or bridged RF intelligence map
This is a candidate boundary, not a decision to place every component in one process. Decoder and other fault-prone native modules may still deserve separate worker processes with narrow, inspectable contracts.
User-interface direction¶
Qt 6 with Qt Quick/QML is the leading C++-centric UI candidate. Its retained, GPU-accelerated scene graph can support a modern RF-analysis interface rather than a traditional desktop-widget appearance.
The native client should be capable of matching or improving the current:
- dark visual language and RF Sentry branding
- high-DPI typography and scaling
- smooth spectrum, waterfall, meters, and overlays
- dockable, resizable, and detachable workspaces
- decoder consoles and investigation panes
- keyboard, mouse, and accessibility behavior
- persistent window and workspace layouts
- restrained, evidence-oriented status presentation
Classic Qt Widgets or an immediate-mode UI should not become the default merely because they are easy to prototype. A prototype must demonstrate that QML can meet the accepted web client's readability and visual quality before a broader UI migration is approved.
RF intelligence map¶
The accepted map is the highest-risk presentation subsystem to rewrite. It is not merely a tile viewer. It currently combines:
- MapLibre GL JS in 2D and globe modes
- retained custom WebGL RF overlays
- station, receiver, precision, and regulatory geography
- capture-time-correct relationships and IQ-timeshift state
- Maidenhead cells and uncertainty presentation
- day/night, terminator, and greyline
- satellites, altitude, ground tracks, passes, and Doppler
- local and optional Internet-backed basemaps
- shared station selection, FCC enrichment, and dossiers
Two migration paths remain viable.
Initial path: preserve the existing map¶
Host the existing map in a constrained Qt WebEngine surface and exchange typed state with the native C++ model through a narrow bridge. This preserves accepted behavior while the rest of the client moves toward native execution. The embedded surface should remain a presentation consumer; it must not become a second station, geography, FCC, or replay authority.
Possible later path: MapLibre Native¶
Port the map to MapLibre Native only after a prototype proves parity for the required globe, custom-overlay, orbital, picking, local-first, and replay behavior. Existing WebGL shaders and MapLibre GL JS lifecycle code cannot be assumed to transfer mechanically to a native renderer.
The embedded-map approach is therefore the preferred first step. A complete native map is an optional optimization, not an entry requirement for the native client.
Shared-client invariants¶
Maintaining both clients is practical only if product semantics live in versioned contracts rather than diverging UI implementations. Both clients must preserve:
- immutable receiver serial identity and configured path identity
- framed IQ acquisition metadata and continuity information
- capture time as the authority for replayed observations
- replay idempotency tied to captured RF rather than processing sessions
- receiver/path-specific geographic location
- observed RF geography distinct from regulatory/home geography
- protocol-aware participant and grid ownership
- station identity distinct from regulatory identity
- factual handling of inactive or ambiguous regulatory records
- shared decoder event schemas and artifact provenance
- explicit live versus historical presentation state
- no projection of future evidence backward during replay
The appliance API should remain client-neutral. Neither client should require
a private receiver-control path that bypasses rfsentry-api, stable demand
ports, or the existing hardware-ownership rules.
Expected advantages¶
- far fewer practical browser-heap constraints for long IQ histories
- deterministic native allocation and memory-pressure policies
- native threads without JavaScript worker and transferable-buffer boundaries
- direct SIMD and mature native DSP/FFT libraries
- lower-copy IQ and audio pipelines
- stronger sustained performance at high sample rates
- direct audio-device and recording-file access
- native SQLite rather than SQLite/WASM and OPFS coordination
- better sanitizer, profiler, crash-dump, and source-trace integration
- reduced exposure to browser background throttling
- more complete CPU, RAM, and GPU observability
- easier scaling to multiple concurrent receivers and longer recordings
Expected costs and risks¶
- a large migration with substantial regression potential
- duplication pressure if the two clients do not share schemas and fixtures
- Windows, Linux, and possibly macOS packaging and release maintenance
- platform GPU differences across Direct3D, Vulkan, Metal, and OpenGL
- native application signing, updates, and dependency distribution
- slower UI iteration than React/CSS in some areas
- reimplementation of browser conveniences and accessibility behavior
- native failures can terminate the application unless risky components stay isolated
- loss of installation-free access if the web client is neglected
- Qt, map, codec, and third-party library licensing must be reviewed before final dependency selection and binary distribution
Large native memory capacity is not permission for unbounded or opaque allocation. The native client should expose explicit DVR, decoder, DSP, map, database, and GPU accounting with operator-controlled retention policies.
Recommended evaluation sequence¶
Stage 0 — contract and workload inventory¶
- Freeze no architecture and change no appliance protocol yet.
- Catalogue the browser's IQ, DSP, decoder, audio, station, FCC, map, and timeshift boundaries.
- Identify code and schemas that can remain shared or generate bindings.
- Capture representative performance and correctness workloads.
Stage 1 — native RF-engine spike¶
Build a headless C++ client that can:
- connect through the supported RF Sentry gateway
- receive and validate framed IQ
- demodulate one receiver with uninterrupted audio
- generate wide and fine spectrum products
- retain and replay a bounded raw-IQ timeline
- demonstrate thread, memory, latency, and continuity diagnostics
The browser remains the correctness reference during this stage.
Stage 2 — focused QML workstation prototype¶
Implement only enough native UI to evaluate the platform:
- receiver connection and status
- spectrum and waterfall
- VFO, mode, gain, passband, and audio controls
- IQ DVR controls
- one representative decoder workspace
Acceptance requires visual and operational quality comparable to the current web client, not merely functional native widgets.
Stage 3 — shared intelligence services¶
- establish native station, observation, geographic, and FCC projections
- preserve current capture-time and replay semantics
- validate native SQLite imports and investigative query behavior
- keep schema fixtures interoperable with the web client
Stage 4 — map bridge¶
- embed the existing RF intelligence map
- define the smallest typed C++/map presentation bridge
- prove selection, dossier, station deltas, receiver location, satellites, and replay reference time
- measure whether the embedded map is actually a bottleneck
Stage 5 — product decision¶
Based on measured evidence, choose among:
- continue supporting the web and hybrid native clients,
- gradually replace selected embedded surfaces with native equivalents, or
- stop the native experiment without disrupting the web product.
No stage implies approval of the next.
Prototype acceptance gates¶
The candidate should advance only if it demonstrates material benefit in the workloads that justify it:
- sustained IQ throughput and decoder stability beyond the browser baseline
- substantially deeper DVR history without browser-style heap failure
- correct capture-time replay across acquisition changes
- responsive audio, waterfall, DSP, and UI under concurrent load
- acceptable CPU/GPU efficiency on supported workstations
- visual quality at least comparable to the accepted web client
- workable map preservation without semantic duplication
- maintainable packaging and updates on the first supported platform
- no regression to the Pi's thin, low-power appliance role
Coexistence policy¶
If the native client becomes a product, RF Sentry should intentionally maintain both clients while their distinct value remains useful:
- The web client remains the universal remote interface and should continue receiving correctness, security, compatibility, and focused feature work.
- The native client may expose workstation-scale performance features that are not safe or practical in every browser.
- Shared wire formats, schemas, fixtures, and terminology should prevent either client from becoming a separate interpretation of RF evidence.
- Features do not need simultaneous pixel-identical UI delivery, but core RF and forensic meaning must stay consistent.
- The native client must not become necessary for appliance administration or ordinary receiver access.
Questions deliberately left open¶
- Which desktop platform should be supported first?
- Should the C++ engine be an in-process library, a supervised local service, or a mixture with isolated decoder processes?
- Which DSP and GPU libraries best match the present algorithms and licenses?
- How much code can be shared through generated schemas versus independent implementations with common conformance fixtures?
- Should durable IQ recordings use SigMF from the first prototype?
- Does the embedded map meet long-term latency and integration needs?
- What release, signing, and automatic-update model is acceptable?
These questions should be answered by small prototypes and measurements, not by committing RF Sentry to a rewrite in advance.