cvv9/ruview

1. This repository is a multi-product monorepo centered on WiFi-based sensing. The active implementation is in v2/, while archive/v1/ preserves an older Python/FastAPI-era stack for reference, tests, and historical behavior. Around that core are firmware, Python bindings, desktop/mobile/web UIs, command-line tools, deployment assets, and extensive docs/ADRs.

2. The lowest layer is edge acquisition on ESP32 hardware. firmware/esp32-csi-node is the primary CSI sensor firmware: it captures WiFi channel state information, handles time sync, mesh coordination, OTA update, NVS config, optional mmWave, and can run a WASM runtime on-device. This layer is the source of raw sensing data that everything else consumes.

3. The main signal-processing boundary lives in v2/crates/wifi-densepose-signal, wifi-densepose-hardware, wifi-densepose-ruvector, wifi-densepose-nn, and wifi-densepose-train. These crates turn raw CSI into cleaned features, CIR/spectrogram representations, coherence-checked measurements, embeddings, and learned outputs. The architecture is explicitly layered from frame parsing and normalization through DSP, topology/graph reasoning, and model inference/training.

4. v2/crates/wifi-densepose-sensing-server is the primary runtime hub. It ingests sensor streams, runs or delegates inference, manages recordings and RVF containers, exposes REST/WebSocket/MQTT surfaces, and contains the domain-specific pipelines for presence, vitals, pose, multistatic bridging, tracking, and semantic detections such as sleeping, distress, meeting, and room occupancy.

5. The sensing server has several outbound integration boundaries. It publishes to MQTT for Home Assistant discovery and automation, exposes Matter and HomeKit/HAP-style bridges through related crates, and supports local discovery and configuration workflows. In the repo, these integrations are treated as adapters around the sensing/event core rather than part of the core signal path.

6. The Home automation/control side is modeled as its own Rust subsystem under v2/crates/homecore-*. Those crates provide a state machine, event bus, automation engine, plugin ABI/runtime, recorder, assist pipeline, and REST/WebSocket API. Conceptually, this is the control plane that consumes sensor-derived events and turns them into actions, registry state, and user-facing home entities.

7. The application layer is split into many domain packages, each built on top of the same sensing primitives. Examples include wifi-densepose-mat for disaster/search-and-rescue workflows, wifi-densepose-pointcloud for fused CSI/depth visualization, nvsim/nvsim-server for simulation, cog-* crates for packaged inference modules, and wifi-densepose-wasm-edge for browser/edge-deployable modules. These are separate bounded contexts sharing the same signal/model substrate.

8. User-facing clients are deliberately decoupled from the sensing engine. v2/crates/wifi-densepose-desktop is a Tauri app for node management, firmware flashing, OTA, mesh discovery, and server control. ui/mobile is a React Native app for live sensing, zones, and vitals. dashboard/, ui/, examples/frontend, and ui/pose-fusion are browser-based visualizations that subscribe to backend APIs and streams rather than processing raw CSI themselves.

9. Python support is a thin but important interoperability layer. python/src exposes PyO3 bindings for core sensing/vitals/privacy functions, while python/wifi_densepose/client provides client libraries for WebSocket, MQTT, and Home Assistant integrations. These packages are the bridge for notebooks, scripts, and external automation in environments where Rust is not the primary runtime.

10. Operationally, the repo is built for local-first execution with optional infrastructure. Docker files, Compose manifests, GitHub Actions workflows, monitoring configs, and logging configs support simulation, CI, firmware builds, release packaging, and observability. The repo also includes benchmark harnesses, test fixtures, and recorded datasets so the signal and model pipeline can be validated offline.

11. The data flow is: ESP32/scan sources capture RF observations → Rust signal/hardware crates validate and transform them → the sensing server or domain app performs inference, tracking, and semantics → outputs are published to APIs, MQTT, Matter/HAP, and UI clients → training/benchmark tools feed curated recordings and models back into the system. That closed loop is the main architectural story of the repo.

12. Two additional boundaries matter for diagrams: first, archive/v1 is a complete but legacy pipeline with its own API, CLI, database, websocket, and tests; second, the plugins/ruview and .claude* directories are operator/tooling surfaces, not runtime product code. They automate setup, flashing, training, verification, and agent workflows around the same underlying sensing stack.