Enhance README.md with architecture and data flow details

- Added a comprehensive architecture diagram illustrating the system components and their interactions.
- Included a detailed data flow description outlining user input, command processing, and state broadcasting.
- Expanded WebSocket event documentation to clarify client-server communication, including payload structures for commands and state updates.
- Updated HTTP endpoint descriptions for better clarity on usage.

README.md

@@ -153,6 +153,92 @@ docker run --gpus all -p 3004:3004 \
 - **Robot selector**: Switch between G1 and Spot
 - **Reset button**: Reset robot to standing pose
 
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                              Browser                                     │
+│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐     │
+│  │   Video Player  │    │  Control Panel  │    │   State Display │     │
+│  │   (MJPEG img)   │    │  (buttons/keys) │    │   (joint data)  │     │
+│  └────────┬────────┘    └────────┬────────┘    └────────▲────────┘     │
+└───────────┼──────────────────────┼──────────────────────┼──────────────┘
+            │ HTTP GET             │ WebSocket            │ WebSocket
+            │ /video_feed          │ command/reset        │ state
+            ▼                      ▼                      │
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         mujoco_server.py                                │
+│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐     │
+│  │  Flask + WSGI   │    │SocketIO Handler │    │  Render Thread  │     │
+│  │  HTTP endpoints │    │  cmd, reset,    │    │  60 FPS loop    │     │
+│  │                 │    │  switch_robot   │    │  MJPEG encode   │     │
+│  └─────────────────┘    └────────┬────────┘    └────────┬────────┘     │
+│                                  │                      │               │
+│                                  ▼                      ▼               │
+│                         ┌───────────────────────────────────┐          │
+│                         │      Active Environment (env)      │          │
+│                         │   G1Env or SpotEnv (Gymnasium)     │          │
+│                         └───────────────────────────────────┘          │
+└─────────────────────────────────────────────────────────────────────────┘
+                                       │
+                                       │ env.step(action)
+                                       ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         Robot Environments                              │
+│                                                                         │
+│  ┌────────────────────────────┐    ┌────────────────────────────┐     │
+│  │         G1Env              │    │         SpotEnv            │     │
+│  │  ┌──────────────────────┐  │    │  ┌──────────────────────┐  │     │
+│  │  │ MuJoCo Model (XML)   │  │    │  │ MuJoCo Model (XML)   │  │     │
+│  │  │ g1_29dof.xml         │  │    │  │ spot.xml             │  │     │
+│  │  └──────────────────────┘  │    │  └──────────────────────┘  │     │
+│  │  ┌──────────────────────┐  │    │  ┌──────────────────────┐  │     │
+│  │  │ Controller           │  │    │  │ Controller           │  │     │
+│  │  │ rl_policy.py         │  │    │  │ (selectable)         │  │     │
+│  │  │ (PyTorch .pt file)   │  │    │  │ - mpc_gait.py        │  │     │
+│  │  └──────────────────────┘  │    │  │ - pympc_controller   │  │     │
+│  │                            │    │  │ - trot_gait.py       │  │     │
+│  │  29 DOF Humanoid           │    │  └──────────────────────┘  │     │
+│  │  - Torso, arms, legs       │    │                            │     │
+│  │  - RL locomotion policy    │    │  12 DOF Quadruped          │     │
+│  └────────────────────────────┘    │  - 4 legs × 3 joints       │     │
+│                                    │  - Gait-based locomotion   │     │
+│                                    └────────────────────────────┘     │
+└─────────────────────────────────────────────────────────────────────────┘
+                                       │
+                                       │ mujoco.mj_step()
+                                       ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         MuJoCo Physics Engine                           │
+│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐     │
+│  │  Rigid Body     │    │   Collision     │    │   Rendering     │     │
+│  │  Dynamics       │    │   Detection     │    │   (OpenGL/      │     │
+│  │                 │    │                 │    │    OSMesa/EGL)  │     │
+│  └─────────────────┘    └─────────────────┘    └─────────────────┘     │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Data Flow
+
+1. **User Input** → Browser captures keyboard/button events
+2. **WebSocket** → Commands sent as `{vx, vy, vyaw}` velocity targets
+3. **Controller** → Converts velocity commands to joint position targets
+4. **MuJoCo** → Simulates physics at 500Hz (0.002s timestep)
+5. **Renderer** → Captures frames at 60 FPS (native) or 30 FPS (Docker)
+6. **MJPEG Stream** → Frames encoded as JPEG and streamed to browser
+7. **State Broadcast** → Robot state sent via WebSocket at render rate
+
+### Controller Architecture
+
+**G1 (Humanoid)**: Uses a pre-trained RL policy (PyTorch) that maps observations (body orientation, joint positions/velocities, commands) to joint position targets.
+
+**Spot (Quadruped)**: Uses gait-based controllers:
+- **MPC Gait**: Phase-based trot with feedback balance control
+- **PyMPC**: Integrates Quadruped-PyMPC's gait generator for timing
+- **Trot**: Simple open-loop sinusoidal gait pattern
+
+All controllers output joint position targets; MuJoCo's built-in PD control tracks these targets.
+
 ## Project Structure
 
 ```
@@ -205,18 +291,92 @@ env = SpotEnv(controller_type='trot')
 
 ### WebSocket Events
 
-**Client to Server:**
-- `command`: `{vx, vy, vyaw}` - Velocity command
-- `reset`: Reset robot to initial pose
-- `switch_robot`: `{robot: "g1" | "spot"}` - Switch robot type
+Connect to `ws://localhost:3004/socket.io/` using Socket.IO client.
+
+#### Client → Server
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `command` | `{vx, vy, vyaw}` | Set velocity command |
+| `reset` | *(none)* | Reset robot to standing pose |
+| `switch_robot` | `{robot}` | Switch active robot |
+| `camera` | `{type, ...}` | Camera control |
+| `camera_follow` | `{follow}` | Toggle camera follow mode |
+
+**`command` payload:**
+```json
+{
+  "vx": 0.5,    // Forward/backward velocity [-1, 1]
+  "vy": 0.0,    // Left/right strafe velocity [-1, 1]
+  "vyaw": 0.0   // Turn rate [-1, 1]
+}
+```
 
-**Server to Client:**
-- `state`: Robot state data (position, orientation, joint angles)
+**`reset`:** No payload - emit the event name only:
+```javascript
+socket.emit('reset');  // No second argument
+```
+Resets the robot to its initial standing pose and resets the camera position.
+
+**`switch_robot` payload:**
+```json
+{
+  "robot": "g1"  // "g1" or "spot"
+}
+```
+
+**`camera` payload:**
+```json
+// Rotate camera
+{"type": "rotate", "dx": 10, "dy": 5}
+
+// Zoom camera
+{"type": "zoom", "dz": -50}
+
+// Pan camera
+{"type": "pan", "dx": 10, "dy": 5}
+
+// Set absolute distance
+{"type": "set_distance", "distance": 3.0}
+```
+
+**`camera_follow` payload:**
+```json
+{
+  "follow": true  // true to follow robot, false for fixed camera
+}
+```
+
+#### Server → Client
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `state` | `{robot, base_height, ...}` | Robot state (broadcast at render rate) |
+
+**`state` payload:**
+```json
+{
+  "robot": "spot",       // Current robot type
+  "base_height": 0.46,   // Robot base height in meters
+  "upright": 0.98,       // Uprightness metric [0-1] (1 = perfectly upright)
+  "steps": 1234,         // Simulation step count
+  "vx": 0.5,             // Current forward velocity command
+  "vy": 0.0,             // Current strafe velocity command
+  "vyaw": 0.0            // Current turn rate command
+}
+```
 
 ### HTTP Endpoints
 
-- `GET /` - Web interface
-- `GET /video_feed` - MJPEG video stream
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | GET | Web interface (HTML/JS) |
+| `/video_feed` | GET | MJPEG video stream |
+
+**Video stream usage:**
+```html
+<img src="http://localhost:3004/video_feed" />
+```
 
 ## License