# cvv9/ruview architecture

> Architecture diagram of the GitHub repository cvv9/ruview, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cvv9/ruview
- Repository: https://github.com/cvv9/ruview

## Overview

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.

Main entry points: [`v2/crates/wifi-densepose-sensing-server`](https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-sensing-server) (Sensing server), [`v2/crates/wifi-densepose-signal`](https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-signal) (Signal pipeline), [`v2/crates/wifi-densepose-hardware`](https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-hardware) (Hardware bridge), [`v2/crates/homecore`](https://github.com/cvv9/ruview/tree/main/v2/crates/homecore) (Homecore)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_edge["Edge acquisition"]
  node_n_firmware["ESP32 CSI node<br/>firmware edge capture"]
end

subgraph group_g_signal["Signal core"]
  node_n_hw["Hardware bridge<br/>rust transport parse"]
  node_n_signal["Signal pipeline<br/>rust CSI DSP"]
  node_n_ruvector["Ruvector core<br/>topology embeddings"]
  node_n_nn["Neural runtime<br/>onnx inference"]
  node_n_train["Training pipeline<br/>model training"]
end

subgraph group_g_runtime["Sensing runtime"]
  node_n_server["Sensing server<br/>ingest and semantics"]
  node_n_bfld["BFLD bridge<br/>mqtt matter bridge"]
end

subgraph group_g_homecore["Home control plane"]
  node_n_homecore["Homecore<br/>automation engine"]
  node_n_homeapi["Homecore API<br/>rest websocket api"]
  node_n_plugins["Homecore plugins<br/>plugin runtime"]
end

subgraph group_g_apps["Application packages"]
  node_n_vitals["Vitals<br/>breathing and heart rate"]
  node_n_mat["MAT app<br/>disaster response"]
  node_n_pointcloud["Pointcloud app<br/>csi depth fusion"]
  node_n_nvsim["NVsim<br/>simulation pipeline"]
  node_n_wasm_edge["WASM edge<br/>browser edge modules"]
end

subgraph group_g_clients["Clients and bridges"]
  node_n_desktop["Desktop app<br/>tauri control app"]
  node_n_mobile["Mobile app<br/>react native client"]
  node_n_web["Web UIs<br/>browser clients"]
  node_n_python["Python bridge<br/>pyo3 bindings and clients"]
  node_n_cli["CLI tools<br/>operator cli"]
end

subgraph group_g_legacy["Legacy archive"]
  node_n_legacy["archive/v1<br/>legacy python stack"]
end

subgraph group_g_tooling["Tooling and ops"]
end

node_n_firmware -->|"CSI frames"| node_n_hw
node_n_hw -->|"normalized stream"| node_n_signal
node_n_signal -->|"coherent features"| node_n_ruvector
node_n_ruvector -->|"embeddings"| node_n_nn
node_n_signal -->|"curated data"| node_n_train
node_n_nn -->|"inference"| node_n_server
node_n_signal -->|"features"| node_n_server
node_n_hw -->|"device ingest"| node_n_server
node_n_server -->|"events"| node_n_bfld
node_n_server -->|"vitals pipeline"| node_n_vitals
node_n_server -->|"rescue semantics"| node_n_mat
node_n_server -->|"fusion data"| node_n_pointcloud
node_n_server -->|"simulation input"| node_n_nvsim
node_n_server -->|"deployable modules"| node_n_wasm_edge
node_n_bfld -->|"automation events"| node_n_homecore
node_n_homecore -->|"control api"| node_n_homeapi
node_n_homecore -->|"plugin hooks"| node_n_plugins
node_n_desktop -->|"flash and ota"| node_n_firmware
node_n_desktop -->|"server control"| node_n_server
node_n_mobile -->|"live api"| node_n_server
node_n_web -->|"dashboards"| node_n_server
node_n_python -->|"ws mqtt ha"| node_n_server
node_n_cli -->|"train ops"| node_n_train
node_n_legacy -.->|"historical reference"| node_n_server

click node_n_firmware "https://github.com/cvv9/ruview/tree/main/firmware/esp32-csi-node"
click node_n_hw "https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-hardware"
click node_n_signal "https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-signal"
click node_n_ruvector "https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-ruvector"
click node_n_nn "https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-nn"
click node_n_train "https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-train"
click node_n_server "https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-sensing-server"
click node_n_bfld "https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-bfld"
click node_n_vitals "https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-vitals"
click node_n_mat "https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-mat"
click node_n_pointcloud "https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-pointcloud"
click node_n_nvsim "https://github.com/cvv9/ruview/tree/main/v2/crates/nvsim"
click node_n_wasm_edge "https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-wasm-edge"
click node_n_desktop "https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-desktop"
click node_n_mobile "https://github.com/cvv9/ruview/tree/main/ui/mobile"
click node_n_web "https://github.com/cvv9/ruview/tree/main/ui"
click node_n_python "https://github.com/cvv9/ruview/tree/main/python"
click node_n_cli "https://github.com/cvv9/ruview/tree/main/tools/ruview-cli"
click node_n_homecore "https://github.com/cvv9/ruview/tree/main/v2/crates/homecore"
click node_n_homeapi "https://github.com/cvv9/ruview/tree/main/v2/crates/homecore-api"
click node_n_plugins "https://github.com/cvv9/ruview/tree/main/v2/crates/homecore-plugins"
click node_n_legacy "https://github.com/cvv9/ruview/tree/main/archive/v1"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_firmware,node_n_legacy toneBlue
class node_n_hw,node_n_signal,node_n_ruvector,node_n_nn,node_n_train toneAmber
class node_n_server,node_n_bfld toneMint
class node_n_homecore,node_n_homeapi,node_n_plugins toneRose
class node_n_vitals,node_n_mat,node_n_pointcloud,node_n_nvsim,node_n_wasm_edge toneIndigo
class node_n_desktop,node_n_mobile,node_n_web,node_n_python,node_n_cli toneTeal
```

## Components

### Edge acquisition

ESP32 CSI capture, sync, mesh, OTA, and on-device runtime.

- [ESP32 CSI node](https://github.com/cvv9/ruview/tree/main/firmware/esp32-csi-node): firmware edge capture · Primary sensor firmware for CSI acquisition, time sync, mesh coordination, OTA, config, and optional WASM/mmWave execution. · `firmware/esp32-csi-node`

### Signal core

Rust crates that normalize CSI, derive features, build representations, and train models.

- [Hardware bridge](https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-hardware): rust transport parse · Frames, sync packets, ESP32 transport, aggregation, and radio-facing bridge logic. · `v2/crates/wifi-densepose-hardware`
- [Signal pipeline](https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-signal): rust CSI DSP · Frame cleaning, normalization, phase handling, CIR/spectrogram, coherence gates, and sensing primitives. · `v2/crates/wifi-densepose-signal`
- [Ruvector core](https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-ruvector): topology embeddings · Graph, viewpoint, signal, MAT, and CRV helpers for coherence, embeddings, and spatial reasoning. · `v2/crates/wifi-densepose-ruvector`
- [Neural runtime](https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-nn): onnx inference · Tensor, translator, RF encoder, and DensePose inference support. · `v2/crates/wifi-densepose-nn`
- [Training pipeline](https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-train): model training · Dataset loading, augmentation, evaluation, proofs, and model training for sensing outputs. · `v2/crates/wifi-densepose-train`

### Sensing runtime

Server-side ingestion, recording, inference, semantic detection, and outbound adapters.

- [Sensing server](https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-sensing-server): ingest and semantics · Primary runtime hub for recordings, RVF containers, inference, semantic pipelines, and external APIs. · `v2/crates/wifi-densepose-sensing-server`
- [BFLD bridge](https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-bfld): mqtt matter bridge · Privacy-gated event/payload pipeline that publishes sensing outputs to MQTT, Home Assistant discovery, and Matter/HAP-style surfaces. · `v2/crates/wifi-densepose-bfld`

### Home control plane

Event-driven home automation, plugins, recorder, assist, API, and migration support.

- [Homecore](https://github.com/cvv9/ruview/tree/main/v2/crates/homecore): automation engine · State machine, event bus, registry, service model, and domain entities for home control. · `v2/crates/homecore`
- [Homecore API](https://github.com/cvv9/ruview/tree/main/v2/crates/homecore-api): rest websocket api · API server, auth, tokens, state, REST, and WebSocket interface for the control plane. · `v2/crates/homecore-api`
- [Homecore plugins](https://github.com/cvv9/ruview/tree/main/v2/crates/homecore-plugins): plugin runtime · Plugin manifest, registry, host ABI, and Wasmtime-backed runtime. · `v2/crates/homecore-plugins`

### Application packages

Domain-specific products built on the shared sensing substrate.

- [Vitals](https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-vitals): breathing and heart rate · Vital-sign preprocessing and anomaly detection used by server and product modules. · `v2/crates/wifi-densepose-vitals`
- [MAT app](https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-mat): disaster response · Search-and-rescue workflows for survivor detection, triage, localization, tracking, and alerting. · `v2/crates/wifi-densepose-mat`
- [Pointcloud app](https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-pointcloud): csi depth fusion · Fused CSI/depth visualization and training-oriented pointcloud pipeline. · `v2/crates/wifi-densepose-pointcloud`
- [NVsim](https://github.com/cvv9/ruview/tree/main/v2/crates/nvsim): simulation pipeline · Scene, sensor, propagation, digitiser, proof, and WASM simulation pipeline. · `v2/crates/nvsim`
- [WASM edge](https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-wasm-edge): browser edge modules · Deployable sensing modules for edge/browser runtimes across many verticals. · `v2/crates/wifi-densepose-wasm-edge`

### Clients and bridges

Desktop, mobile, browser, CLI, Python, and embedded integration surfaces.

- [Desktop app](https://github.com/cvv9/ruview/tree/main/v2/crates/wifi-densepose-desktop): tauri control app · Node management, discovery, flashing, OTA, mesh control, and server operations UI. · `v2/crates/wifi-densepose-desktop`
- [Mobile app](https://github.com/cvv9/ruview/tree/main/ui/mobile): react native client · Live sensing, zones, vitals, MAT views, and server reachability on mobile devices. · `ui/mobile`
- [Web UIs](https://github.com/cvv9/ruview/tree/main/ui): browser clients · Dashboard, observatory, pose-fusion, and related browser views that subscribe to APIs and streams. · `ui`
- [Python bridge](https://github.com/cvv9/ruview/tree/main/python): pyo3 bindings and clients · Rust bindings plus Python client helpers for WebSocket, MQTT, Home Assistant, and notebook use. · `python`
- [CLI tools](https://github.com/cvv9/ruview/tree/main/tools/ruview-cli): operator cli · Command-line utilities for calibration, sensing, training, and module orchestration. · `tools/ruview-cli`

### Legacy archive

Preserved v1 Python/FastAPI-era stack for reference and historical behavior.

- [archive/v1](https://github.com/cvv9/ruview/tree/main/archive/v1): legacy python stack · Complete but archived sensing pipeline with API, CLI, database, websocket, services, and tests. · `archive/v1`

## Connections

- ESP32 CSI node → Hardware bridge: CSI frames · Edge nodes emit raw sensing frames and transport metadata into host-side parsing and transport.
- Hardware bridge → Signal pipeline: normalized stream · Hardware frames are validated, parsed, and converted into canonical sensing inputs.
- Signal pipeline → Ruvector core: coherent features · DSP outputs feed topology, coherence, and embedding layers.
- Ruvector core → Neural runtime: embeddings · Graph and signal abstractions become model-ready representations.
- Signal pipeline → Training pipeline: curated data · Recorded and transformed signal data drives training and evaluation.
- Neural runtime → Sensing server: inference · Model outputs are consumed by the sensing server for runtime decisions.
- Signal pipeline → Sensing server: features · The server can ingest directly transformed CSI and derived measurements.
- Hardware bridge → Sensing server: device ingest · Server-side ingestion may bridge directly from hardware streams.
- Sensing server → BFLD bridge: events · Sensing semantics are published through privacy- and protocol-aware adapters.
- Sensing server → Vitals: vitals pipeline · Presence and physiological sensing reuse shared preprocessing and classification boundaries.
- Sensing server → MAT app: rescue semantics · Domain pipelines for distress, sleeping, triage, tracking, and localization build on server outputs.
- Sensing server → Pointcloud app: fusion data · Server outputs can feed fused visualization and analysis views.
- Sensing server → NVsim: simulation input · Simulated CSI and scene data are used for offline validation and replay.
- Sensing server → WASM edge: deployable modules · Edge/browser modules mirror server-side semantics for alternate runtimes.
- BFLD bridge → Homecore: automation events · BFLD-style sensor events are consumed by the home control plane.
- Homecore → Homecore API: control api · Homecore exposes REST and WebSocket surfaces through the API crate.
- Homecore → Homecore plugins: plugin hooks · Automation behavior is extended via plugin runtime and ABI boundaries.
- Desktop app → ESP32 CSI node: flash and ota · Desktop tooling manages firmware provisioning and device lifecycle.
- Desktop app → Sensing server: server control · Desktop UI configures and observes the sensing runtime.
- Mobile app → Sensing server: live api · Mobile clients subscribe to live sensing, zones, and vitals over backend APIs.
- Web UIs → Sensing server: dashboards · Browser UIs present data from server and domain APIs rather than raw CSI.
- Python bridge → Sensing server: ws mqtt ha · Python clients bridge notebooks and external automation to the runtime.
- CLI tools → Training pipeline: train ops · CLI tooling supports calibration, training, and module orchestration workflows.
- archive/v1 → Sensing server: historical reference · Archived v1 preserves the earlier end-to-end stack and behavior for comparison.