From 2da0c62f8fd02f88fb5bc43d496e222b01ed2357 Mon Sep 17 00:00:00 2001
From: Butterfly Dev <dev@butterfly.local>
Date: Tue, 7 Apr 2026 03:22:37 +0000
Subject: [PATCH] docs: add progress.md with architecture diagram and phase
 checklist

---
 progress.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 progress.md

diff --git a/progress.md b/progress.md
new file mode 100644
index 0000000..8dc5a8c
--- /dev/null
+++ b/progress.md
@@ -0,0 +1,64 @@
+# Butterfly Desktop Environment — Progress
+
+## Overview
+A remote desktop environment with a Rust (Actix) backend and Angular 21 frontend. The system mimics a traditional Windows-like desktop in the browser, receiving display/audio from VM agents with minimal lag.
+
+## Architecture
+```
+┌─────────────┐     WebSocket      ┌──────────────────┐     WebSocket      ┌─────────────┐
+│  Angular 21 │◄──────────────────►│  Rust Actix Server│◄──────────────────►│ VM Agent exe │
+│  (Browser)  │   display/audio    │  (REST + WS)      │   display/audio    │  (Rust)      │
+│             │   HUD commands     │                    │   HUD commands     │             │
+└─────────────┘                    └──────────────────┘                    └─────────────┘
+```
+
+## Checklist
+
+### Phase 1: Rust Backend ✅ (compiles)
+- [x] `server/Cargo.toml` — Dependencies: actix-web 4, actix-ws 0.4, actix-cors, dashmap, parking_lot, serde, uuid, chrono
+- [x] `server/src/main.rs` — Actix HTTP server with CORS, compression, static file serving, SPA fallback
+- [x] `server/src/config.rs` — Env-based config (BUTTERFLY_HOST, BUTTERFLY_PORT, etc.)
+- [x] `server/src/models.rs` — Session, AgentConnection, WsMessage enum (serde-tagged), ApiResponse, HealthInfo
+- [x] `server/src/state.rs` — AppState with DashMap sessions/agents, FrameBuffer ring buffer for late-joiners
+- [x] `server/src/api/` — REST endpoints: GET/POST/DELETE /api/sessions, GET /api/health, POST /api/sessions/{id}/hud
+- [x] `server/src/ws/` — WebSocket handler: agent/viewer connect, display/audio frame relay, HUD forwarding, heartbeat timeout
+- [x] `server/src/stream/` — StreamStats tracker (frame count, byte relay, uptime)
+- [x] `server/static/index.html` — Placeholder loading page
+- [x] Compiles with `cargo check` (warnings only for future-use types)
+
+### Phase 2: Angular 21 Frontend 🔲 (next)
+- [ ] Project scaffold with Angular CLI
+- [ ] Windows-like desktop shell (taskbar, start menu, window manager)
+- [ ] Remote display component (WebSocket frame rendering)
+- [ ] Audio playback component
+- [ ] HUD overlay (mouse/keyboard forwarding)
+- [ ] Built-in apps: File Explorer, Terminal, Settings, Text Editor, Browser
+
+### Phase 3: VM Agent Executable 🔲
+- [ ] Rust desktop agent that captures display and audio
+- [ ] Streams display frames (JPEG/PNG) and audio (Opus/PCM) via WebSocket
+- [ ] Receives HUD commands (mouse, keyboard, resize)
+- [ ] Low-latency design for LAN usage
+
+### Phase 4: Integration & Polish 🔲
+- [ ] End-to-end testing (agent → server → browser)
+- [ ] Session management UI
+- [ ] Multi-session support
+- [ ] Authentication (JWT)
+- [ ] Performance optimization
+
+## Recent Commits
+- `bae17ae` server: fix pong bytes reference — backend compiles
+- `2e55d5c` server: add .gitignore, fix compile errors
+- `0c35db1` server: main.rs — Actix entry point
+- `b2f4f7f` server: fix Cargo.toml dependency versions
+- `94a992d` server: api/sessions.rs — CRUD endpoints
+- `a0b834e` server: stream/ — StreamStats tracker
+- `74591a4` server: ws/handler.rs — WebSocket handler
+- `40bf516` server: api/health.rs
+- `843c7bb` server: api/mod.rs
+- `e00fbf4` server: ws/mod.rs
+- `ff476f1` server: state.rs — AppState
+- `fdde57c` server: config.rs
+- `5c8f848` server: models.rs
+- `bf8e9f7` server: Cargo.toml