docs: Replace ASCII architecture with Mermaid diagrams
Replace the single ASCII box diagram with 3 styled Mermaid diagrams: 1. End-to-End Pipeline — full data flow from WiFi routers through signal processing (6 stages with ruvector crate labels), neural pipeline (graph transformer + SONA), vital signs, to output layer (REST, WebSocket, Analytics, UI). Dark theme with color-coded subsystem groups. 2. Signal Processing Detail — zoomed-in CSI cleanup pipeline showing conjugate multiply, phase unwrap, Hampel filter, min-cut partition, attention gate, STFT, Fresnel, and BVP stages. 3. Deployment Topology — ESP32 mesh (edge) → Rust sensing server (3 ports) → clients (browser, mobile, dashboard, IoT). Component table expanded from 7 to 11 entries with crate/module column linking each component to its source. Co-Authored-By: claude-flow <ruv@ruv.net>
This commit is contained in:
ruv
209
README.md
209
README.md
@@ -707,51 +707,174 @@ The full RuVector ecosystem includes 90+ crates. See [github.com/ruvnet/ruvector
|
|||||||
<details>
|
<details>
|
||||||
<summary><strong>🏗️ System Architecture</strong> — End-to-end data flow from CSI capture to REST/WebSocket API</summary>
|
<summary><strong>🏗️ System Architecture</strong> — End-to-end data flow from CSI capture to REST/WebSocket API</summary>
|
||||||
|
|
||||||
```
|
### End-to-End Pipeline
|
||||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
||||||
│ WiFi Router │ │ WiFi Router │ │ WiFi Router │
|
```mermaid
|
||||||
│ (CSI Source) │ │ (CSI Source) │ │ (CSI Source) │
|
graph TB
|
||||||
└─────────┬───────┘ └─────────┬───────┘ └─────────┬───────┘
|
subgraph HW ["📡 Hardware Layer"]
|
||||||
│ │ │
|
direction LR
|
||||||
└──────────────────────┼──────────────────────┘
|
R1["WiFi Router 1<br/><small>CSI Source</small>"]
|
||||||
│
|
R2["WiFi Router 2<br/><small>CSI Source</small>"]
|
||||||
┌─────────────▼─────────────┐
|
R3["WiFi Router 3<br/><small>CSI Source</small>"]
|
||||||
│ CSI Data Collector │
|
ESP["ESP32-S3 Mesh<br/><small>20 Hz · 56 subcarriers</small>"]
|
||||||
│ (Hardware Interface) │
|
WIN["Windows WiFi<br/><small>RSSI scanning</small>"]
|
||||||
└─────────────┬─────────────┘
|
end
|
||||||
│
|
|
||||||
┌─────────────▼─────────────┐
|
subgraph INGEST ["⚡ Ingestion"]
|
||||||
│ Signal Processor │
|
AGG["Aggregator<br/><small>UDP :5005 · ADR-018 frames</small>"]
|
||||||
│ (RuVector + Phase San.) │
|
BRIDGE["Bridge<br/><small>I/Q → amplitude + phase</small>"]
|
||||||
└─────────────┬─────────────┘
|
end
|
||||||
│
|
|
||||||
┌─────────────▼─────────────┐
|
subgraph SIGNAL ["🔬 Signal Processing — RuVector v2.0.4"]
|
||||||
│ Graph Transformer │
|
direction TB
|
||||||
│ (DensePose + GNN Head) │
|
PHASE["Phase Sanitization<br/><small>SpotFi conjugate multiply</small>"]
|
||||||
└─────────────┬─────────────┘
|
HAMPEL["Hampel Filter<br/><small>Outlier rejection · σ=3</small>"]
|
||||||
│
|
SUBSEL["Subcarrier Selection<br/><small>ruvector-mincut · sensitive/insensitive split</small>"]
|
||||||
┌─────────────▼─────────────┐
|
SPEC["Spectrogram<br/><small>ruvector-attn-mincut · gated STFT</small>"]
|
||||||
│ Vital Signs + Tracker │
|
FRESNEL["Fresnel Geometry<br/><small>ruvector-solver · TX-body-RX distance</small>"]
|
||||||
│ (Breathing, Heart, Pose) │
|
BVP["Body Velocity Profile<br/><small>ruvector-attention · weighted BVP</small>"]
|
||||||
└─────────────┬─────────────┘
|
end
|
||||||
│
|
|
||||||
┌───────────────────────┼───────────────────────┐
|
subgraph ML ["🧠 Neural Pipeline"]
|
||||||
│ │ │
|
direction TB
|
||||||
┌─────────▼─────────┐ ┌─────────▼─────────┐ ┌─────────▼─────────┐
|
GRAPH["Graph Transformer<br/><small>17 COCO keypoints · 16 edges</small>"]
|
||||||
│ REST API │ │ WebSocket API │ │ Analytics │
|
CROSS["Cross-Attention<br/><small>CSI features → body pose</small>"]
|
||||||
│ (Axum / FastAPI) │ │ (Real-time Stream)│ │ (Fall Detection) │
|
SONA["SONA Adapter<br/><small>LoRA rank-4 · EWC++</small>"]
|
||||||
└───────────────────┘ └───────────────────┘ └───────────────────┘
|
end
|
||||||
|
|
||||||
|
subgraph VITAL ["💓 Vital Signs"]
|
||||||
|
direction LR
|
||||||
|
BREATH["Breathing<br/><small>0.1–0.5 Hz · FFT peak</small>"]
|
||||||
|
HEART["Heart Rate<br/><small>0.8–2.0 Hz · FFT peak</small>"]
|
||||||
|
MOTION["Motion Level<br/><small>Variance + band power</small>"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph API ["🌐 Output Layer"]
|
||||||
|
direction LR
|
||||||
|
REST["REST API<br/><small>Axum :3000 · 6 endpoints</small>"]
|
||||||
|
WS["WebSocket<br/><small>:3001 · real-time stream</small>"]
|
||||||
|
ANALYTICS["Analytics<br/><small>Fall · Activity · START triage</small>"]
|
||||||
|
UI["Web UI<br/><small>Three.js · Gaussian splats</small>"]
|
||||||
|
end
|
||||||
|
|
||||||
|
R1 & R2 & R3 --> AGG
|
||||||
|
ESP --> AGG
|
||||||
|
WIN --> BRIDGE
|
||||||
|
AGG --> BRIDGE
|
||||||
|
BRIDGE --> PHASE
|
||||||
|
PHASE --> HAMPEL
|
||||||
|
HAMPEL --> SUBSEL
|
||||||
|
SUBSEL --> SPEC
|
||||||
|
SPEC --> FRESNEL
|
||||||
|
FRESNEL --> BVP
|
||||||
|
BVP --> GRAPH
|
||||||
|
GRAPH --> CROSS
|
||||||
|
CROSS --> SONA
|
||||||
|
SONA --> BREATH & HEART & MOTION
|
||||||
|
BREATH & HEART & MOTION --> REST & WS & ANALYTICS
|
||||||
|
WS --> UI
|
||||||
|
|
||||||
|
style HW fill:#1a1a2e,stroke:#e94560,color:#eee
|
||||||
|
style INGEST fill:#16213e,stroke:#0f3460,color:#eee
|
||||||
|
style SIGNAL fill:#0f3460,stroke:#533483,color:#eee
|
||||||
|
style ML fill:#533483,stroke:#e94560,color:#eee
|
||||||
|
style VITAL fill:#2d132c,stroke:#e94560,color:#eee
|
||||||
|
style API fill:#1a1a2e,stroke:#0f3460,color:#eee
|
||||||
```
|
```
|
||||||
|
|
||||||
| Component | Description |
|
### Signal Processing Detail
|
||||||
|-----------|-------------|
|
|
||||||
| **CSI Processor** | Extracts Channel State Information from WiFi signals (ESP32 or RSSI) |
|
```mermaid
|
||||||
| **Signal Processor** | RuVector-powered phase sanitization, Hampel filter, Fresnel model |
|
graph LR
|
||||||
| **Graph Transformer** | GNN body-graph reasoning with cross-attention CSI-to-pose mapping |
|
subgraph RAW ["Raw CSI Frame"]
|
||||||
| **Vital Signs** | FFT-based breathing (0.1-0.5 Hz) and heartbeat (0.8-2.0 Hz) extraction |
|
IQ["I/Q Samples<br/><small>56–192 subcarriers × N antennas</small>"]
|
||||||
| **REST API** | Axum (Rust) or FastAPI (Python) for data access and control |
|
end
|
||||||
| **WebSocket** | Real-time pose, sensing, and vital sign streaming |
|
|
||||||
| **Analytics** | Fall detection, activity recognition, START triage |
|
subgraph CLEAN ["Phase Cleanup"]
|
||||||
|
CONJ["Conjugate Multiply<br/><small>Remove carrier freq offset</small>"]
|
||||||
|
UNWRAP["Phase Unwrap<br/><small>Remove 2π discontinuities</small>"]
|
||||||
|
HAMPEL2["Hampel Filter<br/><small>Remove impulse noise</small>"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph SELECT ["Subcarrier Intelligence"]
|
||||||
|
MINCUT["Min-Cut Partition<br/><small>ruvector-mincut</small>"]
|
||||||
|
GATE["Attention Gate<br/><small>ruvector-attn-mincut</small>"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph EXTRACT ["Feature Extraction"]
|
||||||
|
STFT["STFT Spectrogram<br/><small>Time-frequency decomposition</small>"]
|
||||||
|
FRESNELZ["Fresnel Zones<br/><small>ruvector-solver</small>"]
|
||||||
|
BVPE["BVP Estimation<br/><small>ruvector-attention</small>"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph OUT ["Output Features"]
|
||||||
|
AMP["Amplitude Matrix"]
|
||||||
|
PHASE2["Phase Matrix"]
|
||||||
|
DOPPLER["Doppler Shifts"]
|
||||||
|
VITALS["Vital Band Power"]
|
||||||
|
end
|
||||||
|
|
||||||
|
IQ --> CONJ --> UNWRAP --> HAMPEL2
|
||||||
|
HAMPEL2 --> MINCUT --> GATE
|
||||||
|
GATE --> STFT --> FRESNELZ --> BVPE
|
||||||
|
BVPE --> AMP & PHASE2 & DOPPLER & VITALS
|
||||||
|
|
||||||
|
style RAW fill:#0d1117,stroke:#58a6ff,color:#c9d1d9
|
||||||
|
style CLEAN fill:#161b22,stroke:#58a6ff,color:#c9d1d9
|
||||||
|
style SELECT fill:#161b22,stroke:#d29922,color:#c9d1d9
|
||||||
|
style EXTRACT fill:#161b22,stroke:#3fb950,color:#c9d1d9
|
||||||
|
style OUT fill:#0d1117,stroke:#8b949e,color:#c9d1d9
|
||||||
|
```
|
||||||
|
|
||||||
|
### Deployment Topology
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TB
|
||||||
|
subgraph EDGE ["Edge (ESP32-S3 Mesh)"]
|
||||||
|
E1["Node 1<br/><small>Kitchen</small>"]
|
||||||
|
E2["Node 2<br/><small>Living room</small>"]
|
||||||
|
E3["Node 3<br/><small>Bedroom</small>"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph SERVER ["Server (Rust · 132 MB Docker)"]
|
||||||
|
SENSE["Sensing Server<br/><small>:3000 REST · :3001 WS · :5005 UDP</small>"]
|
||||||
|
RVF["RVF Model<br/><small>Progressive 3-layer load</small>"]
|
||||||
|
STORE["Time-Series Store<br/><small>In-memory ring buffer</small>"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph CLIENT ["Clients"]
|
||||||
|
BROWSER["Browser<br/><small>Three.js UI · Gaussian splats</small>"]
|
||||||
|
MOBILE["Mobile App<br/><small>WebSocket stream</small>"]
|
||||||
|
DASH["Dashboard<br/><small>REST polling</small>"]
|
||||||
|
IOT["Home Automation<br/><small>MQTT bridge</small>"]
|
||||||
|
end
|
||||||
|
|
||||||
|
E1 -->|"UDP :5005<br/>ADR-018 frames"| SENSE
|
||||||
|
E2 -->|"UDP :5005"| SENSE
|
||||||
|
E3 -->|"UDP :5005"| SENSE
|
||||||
|
SENSE <--> RVF
|
||||||
|
SENSE <--> STORE
|
||||||
|
SENSE -->|"WS :3001<br/>real-time JSON"| BROWSER & MOBILE
|
||||||
|
SENSE -->|"REST :3000<br/>on-demand"| DASH & IOT
|
||||||
|
|
||||||
|
style EDGE fill:#1a1a2e,stroke:#e94560,color:#eee
|
||||||
|
style SERVER fill:#16213e,stroke:#533483,color:#eee
|
||||||
|
style CLIENT fill:#0f3460,stroke:#0f3460,color:#eee
|
||||||
|
```
|
||||||
|
|
||||||
|
| Component | Crate / Module | Description |
|
||||||
|
|-----------|---------------|-------------|
|
||||||
|
| **Aggregator** | `wifi-densepose-hardware` | ESP32 UDP listener, ADR-018 frame parser, I/Q → amplitude/phase bridge |
|
||||||
|
| **Signal Processor** | `wifi-densepose-signal` | SpotFi phase sanitization, Hampel filter, STFT spectrogram, Fresnel geometry, BVP |
|
||||||
|
| **Subcarrier Selection** | `ruvector-mincut` + `ruvector-attn-mincut` | Dynamic sensitive/insensitive partitioning, attention-gated noise suppression |
|
||||||
|
| **Fresnel Solver** | `ruvector-solver` | Sparse Neumann series O(sqrt(n)) for TX-body-RX distance estimation |
|
||||||
|
| **Graph Transformer** | `wifi-densepose-train` | COCO BodyGraph (17 kp, 16 edges), cross-attention CSI→pose, GCN message passing |
|
||||||
|
| **SONA** | `sona` crate | Micro-LoRA (rank-4) adaptation, EWC++ catastrophic forgetting prevention |
|
||||||
|
| **Vital Signs** | `wifi-densepose-signal` | FFT-based breathing (0.1-0.5 Hz) and heartbeat (0.8-2.0 Hz) extraction |
|
||||||
|
| **REST API** | `wifi-densepose-sensing-server` | Axum server: `/api/v1/sensing`, `/health`, `/vital-signs`, `/bssid`, `/sona` |
|
||||||
|
| **WebSocket** | `wifi-densepose-sensing-server` | Real-time pose, sensing, and vital sign streaming on `:3001` |
|
||||||
|
| **Analytics** | `wifi-densepose-mat` | Fall detection, activity recognition, START triage (WiFi-Mat disaster module) |
|
||||||
|
| **Web UI** | `ui/` | Three.js scene, Gaussian splat visualization, signal dashboard |
|
||||||
|
|
||||||
</details>
|
</details>
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user