Architecture Decision Records

Latest proposed decisions:

This folder contains 210 Architecture Decision Records (ADRs) that document every significant technical choice in the RuView / WiFi-DensePose project. (The index tables below list a curated subset per domain; see the directory listing for the full set.)

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
ADR-110	ESP32-C6 firmware extension — Wi-Fi 6 / 802.15.4 / TWT / LP-core	Accepted, P1-P10 complete, firmware-side substrate closed at v0.7.0-esp32. Companion docs: `WITNESS-LOG-110` (13 §A0.x entries · 99.56 % cross-board RX · 104.1 µs smoothed sync stdev · ≤100 µs target met), `ADR-110-REVIEW-GUIDE` (one-page reviewer tour), `ADR-110-BRANCH-STATE` (coordination map vs `feat/adr-115-ha-mqtt-matter`). Host decoders + tests: Python `SyncPacketParser` (10) + Rust `wifi_densepose_hardware::SyncPacket` (15), cross-language hex pin gates drift.

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
ADR-134	First-Class Channel Impulse Response (CIR) Support	Proposed
ADR-135	Empty-Room Baseline Calibration (per-subcarrier Welford statistics)	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
ADR-149	AetherArena: public spatial-intelligence benchmark on Hugging Face	Proposed
ADR-150	RF Foundation Encoder: pose-preserving, subject/room/device-invariant CSI embedding	Proposed
ADR-151	Per-Room Calibration & Specialized Model Training (room-first → bank of small ruVector specialists)	Proposed
ADR-152	WiFi-Pose SOTA 2026 Intake: geometry-conditioned calibration, external benchmarks, foundation-encoder recipe	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
ADR-115	Home Assistant integration via MQTT auto-discovery + Matter bridge (HA-DISCO + HA-FABRIC + HA-MIND)	Accepted (MQTT track) / Proposed (Matter SDK P8b)
ADR-169	adam-mode — light theme toggle for the three.js realtime demo	Proposed
ADR-170	yoga-mode — yoga pose detection, classification, and scoring for the three.js realtime demo	Proposed

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
ADR-263	`@ruvnet/ruview` npm harness — deep review + optimization strategy	Proposed
ADR-264	`@ruvnet/rvagent` MCP server + `@ruv/ruview-cli` — deep review + optimization strategy	Proposed
ADR-265	RuView npm distribution strategy — CI gate, provenance, version single-sourcing, namespace	Proposed
ADR-273	Unified RF spatial world model — umbrella, anti-leakage protocol, acceptance gates	Accepted (P1 implemented)
ADR-274	Universal RF foundation encoder + hardware adapter registry	Accepted (P1 implemented)
ADR-275	RF-aware Gaussian spatial memory	Accepted (P1 implemented)
ADR-276	Physics-guided synthetic RF world generator	Accepted (P1 implemented)
ADR-277	Edge sensing control plane (802.11bf / ETSI ISAC aligned)	Accepted (P1 implemented)
ADR-278	Radar inverse rendering + differentiable RF SLAM research program	Proposed
ADR-279	Native RF frame contract — `RfFrameV2` authoritative, canonical tensor derived	Accepted (implemented)
ADR-280	Active sensing & programmable perception control plane	Accepted (implemented)
ADR-281	BLE Channel Sounding, delay-Doppler tensors, P3162 import, factorized pose	Accepted (implemented)
ADR-282	Ecosystem positioning + mandatory L0–L5 evidence ladder	Accepted
ADR-287	`wifi-densepose-sar` — coherent wideband RF tomography research crate	Accepted (implemented, published)
ADR-285	WASM-first Homecore developer metaharness via `npx homecore`	Accepted (implemented and validated)
ADR-286	`wifi-densepose-sar-harness` — MetaHarness with darwin/router/flywheel	Accepted (implemented, published)
ADR-288	VEIL — compliant-waveform privacy shield against unauthorized WiFi sensing (`wifi-densepose-privshield`)	Proposed (implemented, P1 reference)
ADR-289	`wifi-densepose-privshield-harness` — npm MetaHarness for the VEIL crate (guidance/router/flywheel)	Proposed (implemented, P1)
ADR-290	VEIL end-to-end hardware implementation program — portable C core + multi-provider firmware scaffolds (openwifi/openwrt/nexmon/esp32)	Proposed (P4 scaffolding; C core host-validated)
ADR-291	Public-benchmark evaluation harness — Widar3.0 ingest, split protocols, leakage guards	Accepted (initial implementation)
ADR-292	Wideband 802.11ax CSI ingest — FeitCSI/AX210 adapter, subcarrier-agnostic plumbing	Accepted (initial implementation)
ADR-293	Vitals ground-truth rig — reference ingest, alignment, agreement metrics	Accepted (initial implementation)
ADR-294	WiFi Veil integration — emission-shaping countermeasure as advisory BFLD dependency	Accepted (initial implementation)
ADR-295	Source provenance state machine — synthetic can never present as live	Accepted (initial implementation)
ADR-296	Sensor data-plane hardening — UDP bind control and source allowlist (step one)	Accepted (initial implementation)
ADR-297	Multi-node semantic correctness — per-node inference, node-keyed rate limiting, stale state	Accepted (initial implementation)
ADR-298	Model release sanity gates — block degenerate and mislabeled model artifacts	Accepted (initial implementation)
ADR-299	Repository CSI data-incident controls — ignore rules and pre-commit/CI policy check	Accepted (controls implemented; tree remediation gated)
ADR-300	RuView perception substrate — phased 21-primitive program (calibration, evidence, trust, deployment)	Accepted (program; children ADR-301..317)
ADR-301	Automatic domain calibration — signed, versioned, invalidatable room fingerprint	Accepted (phase 1)
ADR-302	Out-of-distribution detection — KNOWN / DEGRADED / UNKNOWN gating	Accepted (phase 1)
ADR-303	Ground-truth synchronization — reference sensors as a formal validation plane	Proposed (phase 2)
ADR-304	Evidence engine — per-(room,device,subject) accuracy ledger	Accepted (phase 1)
ADR-305	Authenticated sensor identity — RF chain of custody	Accepted (phase 1)
ADR-306	Canonical spatial ontology — one Site→…→Event model for every surface	Accepted (phase 1)
ADR-307	Persistent identity & tracking — privacy-preserving probabilistic tracks	Proposed (phase 2)
ADR-308	Sensor placement optimizer — floorplan + inventory → recommended positions	Proposed (phase 3)
ADR-309	Active sensing — closed-loop RF experiment control	Proposed (phase 3)
ADR-310	802.11bf-native architecture — standardized WLAN sensing as native measurement types	Proposed (phase 2)
ADR-311	Real sensor fusion — uncertainty-aware, multiple observations → one world state	Proposed (phase 2)
ADR-312	Long-term spatial memory — learn the normal physics of a location	Proposed (phase 3)
ADR-313	Counterfactual inference — generative spatial reasoning	Proposed (phase 3)
ADR-314	Information-gain scheduler — sample the most informative radios	Proposed (phase 3)
ADR-315	Digital RF twin — persistent per-deployment RF model	Proposed (phase 3)
ADR-316	Fleet control plane — provisioning to audit trails	Proposed (phase 2)
ADR-317	Multi-domain benchmark scorecard — regressions cannot hide behind pooled accuracy	Accepted (phase 1)
ADR-318	Capability certificates — validated-for-this-environment claims	Accepted (phase 1)
ADR-319	Witness chain — staged, signed epistemic envelope	Accepted (phase 1)
ADR-320	RuView sensor HAL — abstract all sensing hardware to one Observation type	Proposed (phase 2)
ADR-321	Decision policy — action authorization conditioned on certificate class, freshness, uncertainty, evidence	Accepted (phase 1)

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

20 KiB Raw Blame History Unescape Escape