Ruview/docs/adr

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:

1. 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.

2. 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.

3. 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

---

Related

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