Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 50f0fc9

Browse files
ruvnetruvnet
committed
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 <[email protected]>
1 parent 0afd9c5 commit 50f0fc9

1 file changed

Lines changed: 165 additions & 42 deletions

File tree

‎README.md‎

Lines changed: 165 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -707,51 +707,174 @@ The full RuVector ecosystem includes 90+ crates. See [github.com/ruvnet/ruvector
707707
<details>
708708
<summary><strong>🏗️ System Architecture</strong> — End-to-end data flow from CSI capture to REST/WebSocket API</summary>
709709

710+
### End-to-End Pipeline
711+
712+
```mermaid
713+
graph TB
714+
subgraph HW ["📡 Hardware Layer"]
715+
direction LR
716+
R1["WiFi Router 1<br/><small>CSI Source</small>"]
717+
R2["WiFi Router 2<br/><small>CSI Source</small>"]
718+
R3["WiFi Router 3<br/><small>CSI Source</small>"]
719+
ESP["ESP32-S3 Mesh<br/><small>20 Hz · 56 subcarriers</small>"]
720+
WIN["Windows WiFi<br/><small>RSSI scanning</small>"]
721+
end
722+
723+
subgraph INGEST ["⚡ Ingestion"]
724+
AGG["Aggregator<br/><small>UDP :5005 · ADR-018 frames</small>"]
725+
BRIDGE["Bridge<br/><small>I/Q → amplitude + phase</small>"]
726+
end
727+
728+
subgraph SIGNAL ["🔬 Signal Processing — RuVector v2.0.4"]
729+
direction TB
730+
PHASE["Phase Sanitization<br/><small>SpotFi conjugate multiply</small>"]
731+
HAMPEL["Hampel Filter<br/><small>Outlier rejection · σ=3</small>"]
732+
SUBSEL["Subcarrier Selection<br/><small>ruvector-mincut · sensitive/insensitive split</small>"]
733+
SPEC["Spectrogram<br/><small>ruvector-attn-mincut · gated STFT</small>"]
734+
FRESNEL["Fresnel Geometry<br/><small>ruvector-solver · TX-body-RX distance</small>"]
735+
BVP["Body Velocity Profile<br/><small>ruvector-attention · weighted BVP</small>"]
736+
end
737+
738+
subgraph ML ["🧠 Neural Pipeline"]
739+
direction TB
740+
GRAPH["Graph Transformer<br/><small>17 COCO keypoints · 16 edges</small>"]
741+
CROSS["Cross-Attention<br/><small>CSI features → body pose</small>"]
742+
SONA["SONA Adapter<br/><small>LoRA rank-4 · EWC++</small>"]
743+
end
744+
745+
subgraph VITAL ["💓 Vital Signs"]
746+
direction LR
747+
BREATH["Breathing<br/><small>0.1–0.5 Hz · FFT peak</small>"]
748+
HEART["Heart Rate<br/><small>0.8–2.0 Hz · FFT peak</small>"]
749+
MOTION["Motion Level<br/><small>Variance + band power</small>"]
750+
end
751+
752+
subgraph API ["🌐 Output Layer"]
753+
direction LR
754+
REST["REST API<br/><small>Axum :3000 · 6 endpoints</small>"]
755+
WS["WebSocket<br/><small>:3001 · real-time stream</small>"]
756+
ANALYTICS["Analytics<br/><small>Fall · Activity · START triage</small>"]
757+
UI["Web UI<br/><small>Three.js · Gaussian splats</small>"]
758+
end
759+
760+
R1 & R2 & R3 --> AGG
761+
ESP --> AGG
762+
WIN --> BRIDGE
763+
AGG --> BRIDGE
764+
BRIDGE --> PHASE
765+
PHASE --> HAMPEL
766+
HAMPEL --> SUBSEL
767+
SUBSEL --> SPEC
768+
SPEC --> FRESNEL
769+
FRESNEL --> BVP
770+
BVP --> GRAPH
771+
GRAPH --> CROSS
772+
CROSS --> SONA
773+
SONA --> BREATH & HEART & MOTION
774+
BREATH & HEART & MOTION --> REST & WS & ANALYTICS
775+
WS --> UI
776+
777+
style HW fill:#1a1a2e,stroke:#e94560,color:#eee
778+
style INGEST fill:#16213e,stroke:#0f3460,color:#eee
779+
style SIGNAL fill:#0f3460,stroke:#533483,color:#eee
780+
style ML fill:#533483,stroke:#e94560,color:#eee
781+
style VITAL fill:#2d132c,stroke:#e94560,color:#eee
782+
style API fill:#1a1a2e,stroke:#0f3460,color:#eee
710783
```
711-
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
712-
│ WiFi Router │ │ WiFi Router │ │ WiFi Router │
713-
│ (CSI Source) │ │ (CSI Source) │ │ (CSI Source) │
714-
└─────────┬───────┘ └─────────┬───────┘ └─────────┬───────┘
715-
│ │ │
716-
└──────────────────────┼──────────────────────┘
717-
│
718-
┌─────────────▼─────────────┐
719-
│ CSI Data Collector │
720-
│ (Hardware Interface) │
721-
└─────────────┬─────────────┘
722-
│
723-
┌─────────────▼─────────────┐
724-
│ Signal Processor │
725-
│ (RuVector + Phase San.) │
726-
└─────────────┬─────────────┘
727-
│
728-
┌─────────────▼─────────────┐
729-
│ Graph Transformer │
730-
│ (DensePose + GNN Head) │
731-
└─────────────┬─────────────┘
732-
│
733-
┌─────────────▼─────────────┐
734-
│ Vital Signs + Tracker │
735-
│ (Breathing, Heart, Pose) │
736-
└─────────────┬─────────────┘
737-
│
738-
┌───────────────────────┼───────────────────────┐
739-
│ │ │
740-
┌─────────▼─────────┐ ┌─────────▼─────────┐ ┌─────────▼─────────┐
741-
│ REST API │ │ WebSocket API │ │ Analytics │
742-
│ (Axum / FastAPI) │ │ (Real-time Stream)│ │ (Fall Detection) │
743-
└───────────────────┘ └───────────────────┘ └───────────────────┘
784+
785+
### Signal Processing Detail
786+
787+
```mermaid
788+
graph LR
789+
subgraph RAW ["Raw CSI Frame"]
790+
IQ["I/Q Samples<br/><small>56–192 subcarriers × N antennas</small>"]
791+
end
792+
793+
subgraph CLEAN ["Phase Cleanup"]
794+
CONJ["Conjugate Multiply<br/><small>Remove carrier freq offset</small>"]
795+
UNWRAP["Phase Unwrap<br/><small>Remove 2π discontinuities</small>"]
796+
HAMPEL2["Hampel Filter<br/><small>Remove impulse noise</small>"]
797+
end
798+
799+
subgraph SELECT ["Subcarrier Intelligence"]
800+
MINCUT["Min-Cut Partition<br/><small>ruvector-mincut</small>"]
801+
GATE["Attention Gate<br/><small>ruvector-attn-mincut</small>"]
802+
end
803+
804+
subgraph EXTRACT ["Feature Extraction"]
805+
STFT["STFT Spectrogram<br/><small>Time-frequency decomposition</small>"]
806+
FRESNELZ["Fresnel Zones<br/><small>ruvector-solver</small>"]
807+
BVPE["BVP Estimation<br/><small>ruvector-attention</small>"]
808+
end
809+
810+
subgraph OUT ["Output Features"]
811+
AMP["Amplitude Matrix"]
812+
PHASE2["Phase Matrix"]
813+
DOPPLER["Doppler Shifts"]
814+
VITALS["Vital Band Power"]
815+
end
816+
817+
IQ --> CONJ --> UNWRAP --> HAMPEL2
818+
HAMPEL2 --> MINCUT --> GATE
819+
GATE --> STFT --> FRESNELZ --> BVPE
820+
BVPE --> AMP & PHASE2 & DOPPLER & VITALS
821+
822+
style RAW fill:#0d1117,stroke:#58a6ff,color:#c9d1d9
823+
style CLEAN fill:#161b22,stroke:#58a6ff,color:#c9d1d9
824+
style SELECT fill:#161b22,stroke:#d29922,color:#c9d1d9
825+
style EXTRACT fill:#161b22,stroke:#3fb950,color:#c9d1d9
826+
style OUT fill:#0d1117,stroke:#8b949e,color:#c9d1d9
827+
```
828+
829+
### Deployment Topology
830+
831+
```mermaid
832+
graph TB
833+
subgraph EDGE ["Edge (ESP32-S3 Mesh)"]
834+
E1["Node 1<br/><small>Kitchen</small>"]
835+
E2["Node 2<br/><small>Living room</small>"]
836+
E3["Node 3<br/><small>Bedroom</small>"]
837+
end
838+
839+
subgraph SERVER ["Server (Rust · 132 MB Docker)"]
840+
SENSE["Sensing Server<br/><small>:3000 REST · :3001 WS · :5005 UDP</small>"]
841+
RVF["RVF Model<br/><small>Progressive 3-layer load</small>"]
842+
STORE["Time-Series Store<br/><small>In-memory ring buffer</small>"]
843+
end
844+
845+
subgraph CLIENT ["Clients"]
846+
BROWSER["Browser<br/><small>Three.js UI · Gaussian splats</small>"]
847+
MOBILE["Mobile App<br/><small>WebSocket stream</small>"]
848+
DASH["Dashboard<br/><small>REST polling</small>"]
849+
IOT["Home Automation<br/><small>MQTT bridge</small>"]
850+
end
851+
852+
E1 -->|"UDP :5005<br/>ADR-018 frames"| SENSE
853+
E2 -->|"UDP :5005"| SENSE
854+
E3 -->|"UDP :5005"| SENSE
855+
SENSE <--> RVF
856+
SENSE <--> STORE
857+
SENSE -->|"WS :3001<br/>real-time JSON"| BROWSER & MOBILE
858+
SENSE -->|"REST :3000<br/>on-demand"| DASH & IOT
859+
860+
style EDGE fill:#1a1a2e,stroke:#e94560,color:#eee
861+
style SERVER fill:#16213e,stroke:#533483,color:#eee
862+
style CLIENT fill:#0f3460,stroke:#0f3460,color:#eee
744863
```
745864

746-
| Component | Description |
747-
|-----------|-------------|
748-
| **CSI Processor** | Extracts Channel State Information from WiFi signals (ESP32 or RSSI) |
749-
| **Signal Processor** | RuVector-powered phase sanitization, Hampel filter, Fresnel model |
750-
| **Graph Transformer** | GNN body-graph reasoning with cross-attention CSI-to-pose mapping |
751-
| **Vital Signs** | FFT-based breathing (0.1-0.5 Hz) and heartbeat (0.8-2.0 Hz) extraction |
752-
| **REST API** | Axum (Rust) or FastAPI (Python) for data access and control |
753-
| **WebSocket** | Real-time pose, sensing, and vital sign streaming |
754-
| **Analytics** | Fall detection, activity recognition, START triage |
865+
| Component | Crate / Module | Description |
866+
|-----------|---------------|-------------|
867+
| **Aggregator** | `wifi-densepose-hardware` | ESP32 UDP listener, ADR-018 frame parser, I/Q → amplitude/phase bridge |
868+
| **Signal Processor** | `wifi-densepose-signal` | SpotFi phase sanitization, Hampel filter, STFT spectrogram, Fresnel geometry, BVP |
869+
| **Subcarrier Selection** | `ruvector-mincut` + `ruvector-attn-mincut` | Dynamic sensitive/insensitive partitioning, attention-gated noise suppression |
870+
| **Fresnel Solver** | `ruvector-solver` | Sparse Neumann series O(sqrt(n)) for TX-body-RX distance estimation |
871+
| **Graph Transformer** | `wifi-densepose-train` | COCO BodyGraph (17 kp, 16 edges), cross-attention CSI→pose, GCN message passing |
872+
| **SONA** | `sona` crate | Micro-LoRA (rank-4) adaptation, EWC++ catastrophic forgetting prevention |
873+
| **Vital Signs** | `wifi-densepose-signal` | FFT-based breathing (0.1-0.5 Hz) and heartbeat (0.8-2.0 Hz) extraction |
874+
| **REST API** | `wifi-densepose-sensing-server` | Axum server: `/api/v1/sensing`, `/health`, `/vital-signs`, `/bssid`, `/sona` |
875+
| **WebSocket** | `wifi-densepose-sensing-server` | Real-time pose, sensing, and vital sign streaming on `:3001` |
876+
| **Analytics** | `wifi-densepose-mat` | Fall detection, activity recognition, START triage (WiFi-Mat disaster module) |
877+
| **Web UI** | `ui/` | Three.js scene, Gaussian splat visualization, signal dashboard |
755878

756879
</details>
757880

0 commit comments

Comments
 (0)