## Introduction

RuView is a WiFi-based human pose estimation system built on ESP32 CSI (Channel State Information). Today, managing a RuView deployment requires juggling **6+ disconnected CLI tools**: `esptool.py` for flashing, `provision.py` for NVS configuration, `curl` for OTA and WASM management, `cargo run` for the sensing server, a browser for visualization, and manual IP tracking for node discovery. There is no single tool that provides a unified view of the entire deployment — from ESP32 hardware through the sensing pipeline to pose visualization.

This issue tracks the implementation of **RuView Desktop** — a Tauri v2 cross-platform desktop application that replaces all of these tools with a single, cohesive interface. The application is designed as the **control plane** for the RuView platform, managing the full lifecycle: discover, flash, provision, OTA, load WASM, observe sensing.

### Why Tauri (Not Electron/Flutter/Web)

| Requirement | Why Desktop is Required |
|-------------|------------------------|
| Serial port access | Browser/PWA cannot touch COM/tty ports for firmware flashing |
| Raw UDP sockets | Node discovery via broadcast probes requires raw socket access |
| Filesystem access | Firmware binaries, WASM modules, model files live on local disk |
| Process management | Sensing server runs as a managed child process (sidecar) |
| Small binary | Tauri ~20 MB vs Electron ~150 MB |
| Rust integration | Shares crates with existing workspace |

### UI Design Language

The frontend uses a **Foundation Book** design scheme with **Unity Editor-inspired** UI panels. Think: clean typographic hierarchy, structured panels with dockable regions, monospaced data displays, and a professional dark theme with accent colors for status indicators. Powered by rUv.

---

## ADR-052 Deep Overview

The full architecture is documented in [ADR-052](https://github.com/ruvnet/RuView/blob/feat/tauri-desktop-frontend/docs/adr/ADR-052-tauri-desktop-frontend.md) with a companion [DDD bounded contexts appendix](https://github.com/ruvnet/RuView/blob/feat/tauri-desktop-frontend/docs/adr/ADR-052-ddd-bounded-contexts.md).

### Workspace Integration

The desktop app is a new Rust crate (`wifi-densepose-desktop`) in the existing workspace, sharing types with the sensing server and hardware crate. The frontend uses React + Vite + TypeScript with a Foundation Book / Unity-inspired design system.

### 6 Rust Command Groups

| Group | Commands | Bounded Context |
|-------|----------|-----------------|
| **Discovery** | `discover_nodes`, `get_node_status`, `watch_nodes` | Device Discovery |
| **Flash** | `list_serial_ports`, `flash_firmware`, `read_chip_info` | Firmware Management |
| **OTA** | `ota_update`, `ota_status`, `ota_batch_update` | Firmware Management |
| **WASM** | `wasm_list`, `wasm_upload`, `wasm_control` | Edge Module |
| **Server** | `start_server`, `stop_server`, `server_status` | Sensing Pipeline |
| **Provision** | `provision_node`, `read_nvs` | Configuration |

### 7 Frontend Pages

| Page | Purpose |
|------|---------|
| **Dashboard** | Node count (online/offline), server status, quick actions, activity feed |
| **Node Detail** | Single node deep-dive: firmware, health, TDM config, WASM modules |
| **Flash Firmware** | 3-step wizard: select port, select firmware, flash with progress bar |
| **WASM Modules** | Drag-and-drop upload, module list with start/stop/unload |
| **Sensing View** | Live CSI heatmap, pose skeleton overlay, vital signs |
| **Mesh Topology** | Force-directed graph: TDM slots, sync drift, node health |
| **Settings** | Server ports, bind address, OTA PSK, UI theme |

### DDD Bounded Contexts

6 bounded contexts with 9 aggregates, 25+ domain events, and 3 anti-corruption layers. See the [DDD appendix](https://github.com/ruvnet/RuView/blob/feat/tauri-desktop-frontend/docs/adr/ADR-052-ddd-bounded-contexts.md) for full details.

| Context | Aggregate Root(s) | Key Events |
|---------|--------------------|------------|
| Device Discovery | `NodeRegistry` | `NodeDiscovered`, `NodeWentOffline`, `ScanCompleted` |
| Firmware Management | `FlashSession`, `OtaSession`, `BatchOtaSession` | `FlashProgress`, `OtaCompleted`, `BatchOtaCompleted` |
| Configuration | `ProvisioningSession` | `NodeProvisioned`, `ConfigReadBack` |
| Sensing Pipeline | `SensingServer`, `WebSocketSession` | `ServerStarted`, `FrameReceived` |
| Edge Module (WASM) | `ModuleRegistry` | `ModuleUploaded`, `ModuleStarted` |
| Visualization | Query model (no aggregate) | Consumes all upstream events |

### Persistent Node Registry

Stored in `~/.ruview/nodes.db` (SQLite). On startup, previously known nodes load as Offline and reconcile against fresh discovery. The app remembers the mesh across restarts.

### OTA Safety Gate

The `TdmSafe` rolling update strategy updates even-slot nodes first, then odd-slot nodes, ensuring adjacent nodes are never offline simultaneously during mesh-wide firmware updates.

### Platform-Specific Considerations

| Platform | Concern | Solution |
|----------|---------|----------|
| macOS | USB serial drivers need signing on Sequoia+ | Document driver requirements |
| Windows | COM port naming, UAC | Auto-detect via registry |
| Linux | Serial port permissions | Bundle udev rules installer |

---

## Implementation Phases

| Phase | Scope | Priority |
|-------|-------|----------|
| 1. Skeleton | Tauri scaffolding, workspace integration, React window | P0 |
| 2. Discovery | Serial ports, node discovery, dashboard cards | P0 |
| 3. Flash | espflash integration, flashing wizard | P0 |
| 4. Server | Sidecar sensing server, log viewer | P1 |
| 5. OTA | HTTP OTA with PSK auth, batch TdmSafe | P1 |
| 6. Provisioning | NVS GUI form, read-back, mesh presets | P1 |
| 7. WASM | Module upload/list/control | P2 |
| 8. Sensing | WebSocket, live charts, pose overlay | P2 |
| 9. Mesh View | Topology graph, TDM visualization | P2 |
| 10. Polish | App signing, auto-update, onboarding wizard | P3 |

Total estimated effort: ~11 weeks for a single developer.

## Acceptance Criteria

- [ ] Tauri app builds on Windows, macOS, Linux
- [ ] Can discover ESP32 nodes on local network
- [ ] Node registry persists across restarts
- [ ] Can flash firmware via serial port (no Python dependency)
- [ ] Can push OTA updates with PSK authentication
- [ ] Rolling OTA with TdmSafe strategy for mesh deployments
- [ ] Can upload/manage WASM modules on nodes
- [ ] Can start/stop sensing server and view live logs
- [ ] Can view real-time sensing data via WebSocket
- [ ] Can provision NVS config via GUI form
- [ ] Mesh topology visualization shows TDM slots and health
- [ ] Binary size less than 30 MB
- [ ] Foundation Book / Unity-inspired UI design system
- [ ] Each new Rust module has unit tests

## Dependencies

- ADR-012: ESP32 CSI Sensor Mesh
- ADR-039: ESP32 Edge Intelligence
- ADR-040: WASM Programmable Sensing
- ADR-044: Provisioning Tool Enhancements
- ADR-050: Quality Engineering Security Hardening
- ADR-051: Sensing Server Decomposition
- ADR-053: UI Design System (Foundation Book + Unity-inspired)

## Branch

[`feat/tauri-desktop-frontend`](https://github.com/ruvnet/RuView/tree/feat/tauri-desktop-frontend)

## References

- [ADR-052: Tauri Desktop Frontend](https://github.com/ruvnet/RuView/blob/feat/tauri-desktop-frontend/docs/adr/ADR-052-tauri-desktop-frontend.md)
- [ADR-052 DDD Appendix](https://github.com/ruvnet/RuView/blob/feat/tauri-desktop-frontend/docs/adr/ADR-052-ddd-bounded-contexts.md)
- [Tauri v2 Documentation](https://v2.tauri.app/)
- [espflash crate](https://crates.io/crates/espflash)

Powered by **rUv**
