mirror of https://github.com/ruvnet/RuView synced 2026-06-09 10:13:17 +00:00

Files

T

rUv 9d4f7820b2 docs(adr): ADR-098 — evaluate midstream for RuView's CSI/WS/mesh pipeline (Rejected) (#553 )

`vendor/midstream` is a git submodule of RuView but no `v2/crates/*` depends
on a `midstreamer-*` crate and no Rust source uses one — i.e. it is vendored
but not consumed, the same state `vendor/rvcsi` was in before ADR-097.

ADR-098 evaluates whether to change that. The candidate seams (from the
prompt) were:

  1. Streaming / pub-sub for the WS fan-out (today: `tokio::sync::broadcast`
     at `wifi-densepose-sensing-server/src/main.rs:4769`).
  2. CSI → DSP → event pipeline (today: rvcsi-events::EventPipeline, just
     adopted by ADR-097).
  3. Multi-source merging / TDM for the ESP32 mesh (ADR-029, ADR-073).
  4. Backpressure / flow control between the UDP receiver and downstream
     consumers (firmware `stream_sender` ENOMEM; host-side bounded
     broadcast channel).

Reading all six midstream workspace crates end-to-end
(`vendor/midstream/crates/{temporal-compare,nanosecond-scheduler,
temporal-attractor-studio,temporal-neural-solver,strange-loop,
quic-multistream}/src/*.rs` — ~3,455 LOC) shows midstream's identity
unambiguously: `Cargo.toml:16` calls itself "Real-time LLM streaming with
inflight analysis", the README frames it as analyzing *LLM token streams*
in real time, and zero hits across the workspace for `csi|wifi|sensing|
sensor`. midstream's abstractions are LLM-token / dashboard-telemetry
shaped; RuView's pipeline is RF-frame / event-detector shaped.

Decisions:

  D1 — WS fan-out: keep `tokio::sync::broadcast::channel::<String>(256)`.
       midstream offers no equivalent in-process broadcast primitive.
  D2 — CSI pipeline: keep `rvcsi-events::EventPipeline` (deterministic,
       single-frame-at-a-time, replayable per ADR-095 D9). midstream's
       attractor / LTL crates operate on multi-dimensional trajectories,
       not validated single CSI frames.
  D3 — TDM / aggregator: keep `wifi-densepose-hardware::aggregator` +
       firmware-side TDM. midstream has no UDP merger and no cross-device
       wall-clock scheduler.
  D4 — Backpressure: the firmware ENOMEM rate-limit and the bounded host
       `broadcast` channel are correct at each end; midstream's QUIC
       primitives don't help the actual UDP+WS topology.
  D5 — Carve-out: `midstreamer-temporal-compare` (DTW / LCS / Levenshtein)
       is a plausible future-evaluation option if a *second* DTW use case
       appears in RuView. RuvSense already has one (`gesture.rs`).
  D6 — Carve-out: `midstreamer-scheduler` (deadline-aware, EDF / LLF /
       RM) is a plausible future option if the cluster-Pi aggregator ever
       takes over real-time scheduling. Today that lives in firmware.
  D7 — Submodule: keep `vendor/midstream` pinned at `30fe5eb` as reference
       material; do not advance the pin per-release (unlike vendor/rvcsi
       under ADR-097 D7) because there is no in-build consumer.
  D8 — Docs: cross-reference, don't import. ADR-098 added to
       `docs/adr/README.md`.

Status: Rejected (with named re-evaluation triggers in §6 — second DTW use
case, host-side real-time scheduler, midstream gains a CSI adapter, or a
QUIC-to-external-client requirement that WS can't service).

2026-05-17 17:49:21 -04:00

8.7 KiB

Raw Permalink Blame History

Architecture Decision Records

This folder contains 44 Architecture Decision Records (ADRs) that document every significant technical choice in the RuView / WiFi-DensePose project.

Why ADRs?

Building a system that turns WiFi signals into human pose estimation involves hundreds of non-obvious decisions: which signal processing algorithms to use, how to bridge ESP32 firmware to a Rust pipeline, whether to run inference on-device or on a server, how to handle multi-person separation with limited subcarriers.

ADRs capture the context, options considered, decision made, and consequences for each of these choices. They serve three purposes:

Institutional memory — Six months from now, anyone (human or AI) can read why we chose IIR bandpass filters over FIR for vital sign extraction, not just see the code.
AI-assisted development — When an AI agent works on this codebase, ADRs give it the constraints and rationale it needs to make changes that align with the existing architecture. Without them, AI-generated code tends to drift — reinventing patterns that already exist, contradicting earlier decisions, or optimizing for the wrong tradeoffs.
Review checkpoints — Each ADR is a reviewable artifact. When a proposed change touches the architecture, the ADR forces the author to articulate tradeoffs before writing code, not after.

ADRs and Domain-Driven Design

The project uses Domain-Driven Design (DDD) to organize code into bounded contexts — each with its own language, types, and responsibilities. ADRs and DDD work together:

ADRs define boundaries: ADR-029 (RuvSense) established multistatic sensing as a separate bounded context from single-node CSI. ADR-042 (CHCI) defined a new aggregate root for coherent channel imaging.
DDD models define the language: The RuvSense domain model defines terms like "coherence gate", "dwell time", and "TDM slot" that ADRs reference precisely.
Together they prevent drift: An AI agent reading ADR-039 knows that edge processing tiers are configured via NVS keys, not compile-time flags — because the ADR says so. The DDD model tells it which aggregate owns that configuration.

How ADRs are structured

Each ADR follows a consistent format:

Context — What problem or gap prompted this decision
Decision — What we chose to do and how
Consequences — What improved, what got harder, and what risks remain
References — Related ADRs, papers, and code paths

Statuses: Proposed (under discussion), Accepted (approved and/or implemented), Superseded (replaced by a later ADR).

ADR Index

Hardware and firmware

ADR	Title	Status
ADR-012	ESP32 CSI Sensor Mesh for Distributed Sensing	Accepted (partial)
ADR-018	ESP32 Development Implementation Path	Proposed
ADR-028	ESP32 Capability Audit and Witness Record	Accepted
ADR-029	RuvSense Multistatic Sensing Mode (TDM, channel hopping)	Proposed
ADR-032	Multistatic Mesh Security Hardening	Accepted
ADR-039	ESP32-S3 Edge Intelligence Pipeline (on-device vitals)	Accepted (hardware-validated)
ADR-040	WASM Programmable Sensing (Tier 3)	Accepted
ADR-041	WASM Module Collection (65 edge modules)	Accepted (hardware-validated)
ADR-044	Provisioning Tool Enhancements	Proposed

Signal processing and sensing

ADR	Title	Status
ADR-013	Feature-Level Sensing on Commodity Gear	Accepted
ADR-014	SOTA Signal Processing Algorithms	Accepted
ADR-021	Vital Sign Detection (breathing, heart rate)	Partial
ADR-030	Persistent Field Model and Drift Detection	Proposed
ADR-033	CRV Signal Line Sensing Integration	Proposed
ADR-037	Multi-Person Pose Detection from Single ESP32	Proposed
ADR-042	Coherent Human Channel Imaging (beyond CSI)	Proposed

Machine learning and training

ADR	Title	Status
ADR-005	SONA Self-Learning for Pose Estimation	Partial
ADR-006	GNN-Enhanced CSI Pattern Recognition	Partial
ADR-015	Public Dataset Strategy (MM-Fi, Wi-Pose)	Accepted
ADR-016	RuVector Training Pipeline Integration	Accepted
ADR-017	RuVector Signal + MAT Integration	Proposed
ADR-020	Migrate AI Inference to Rust (ONNX Runtime)	Accepted
ADR-023	Trained DensePose Model with RuVector Pipeline	Proposed
ADR-024	Project AETHER: Contrastive CSI Embeddings	Required
ADR-027	Project MERIDIAN: Cross-Environment Generalization	Proposed

Platform and UI

ADR	Title	Status
ADR-019	Sensing-Only UI with Gaussian Splats	Accepted
ADR-022	Windows WiFi Enhanced Fidelity (multi-BSSID)	Partial
ADR-025	macOS CoreWLAN WiFi Sensing	Proposed
ADR-031	RuView Sensing-First RF Mode	Proposed
ADR-034	Expo React Native Mobile App	Accepted
ADR-035	Live Sensing UI Accuracy and Data Transparency	Accepted
ADR-036	Training Pipeline UI Integration	Proposed
ADR-043	Sensing Server UI API Completion (14 endpoints)	Accepted

Architecture and infrastructure

ADR	Title	Status
ADR-001	WiFi-Mat Disaster Detection Architecture	Accepted
ADR-002	RuVector RVF Integration Strategy	Superseded
ADR-003	RVF Cognitive Containers for CSI	Proposed
ADR-004	HNSW Vector Search for Fingerprinting	Partial
ADR-007	Post-Quantum Cryptography for Sensing	Proposed
ADR-008	Distributed Consensus for Multi-AP	Proposed
ADR-009	RVF WASM Runtime for Edge Deployment	Proposed
ADR-010	Witness Chains for Audit Trail Integrity	Proposed
ADR-011	Proof-of-Reality and Mock Elimination	Proposed
ADR-026	Survivor Track Lifecycle (MAT crate)	Accepted
ADR-038	Sublinear GOAP for Roadmap Optimization	Proposed
ADR-095	rvCSI — Edge RF Sensing Runtime Platform	Proposed
ADR-096	rvCSI — Crate Topology, the napi-c Shim, and the napi-rs Node Surface	Proposed
ADR-097	Adopt rvCSI as RuView's primary CSI runtime (phased adoption)	Proposed
ADR-098	Evaluate `ruvnet/midstream` for RuView's CSI / WebSocket / mesh pipeline	Rejected
ADR-099	Adopt midstream as RuView's real-time introspection + low-latency tap	Proposed

DDD Domain Models — Bounded context definitions, aggregate roots, and ubiquitous language
User Guide — Setup, API reference, and hardware instructions
Build Guide — Building from source

8.7 KiB Raw Permalink Blame History