claudetools/projects/msp-tools/guru-connect/README.md

# GuruConnect - Remote Desktop Solution

**Project Type:** Internal Tool / MSP Platform Component
**Status:** Phase 1 MVP Development
**Technology Stack:** Rust, React, WebSockets, Protocol Buffers
**Integration:** GuruRMM platform

## Project Overview

GuruConnect is a remote desktop solution similar to ScreenConnect/ConnectWise Control, designed for fast, secure remote screen control and backstage tools for Windows systems. Built as an integrated component of the GuruRMM platform.

**Goal:** Provide MSP technicians with enterprise-grade remote desktop capabilities fully integrated with GuruRMM's monitoring and management features.

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      GuruConnect System                       │
└─────────────────────────────────────────────────────────────┘

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│   Dashboard     │         │  GuruConnect    │         │  GuruConnect    │
│   (React)       │◄──WSS──►│  Server (Rust)  │◄──WSS──►│  Agent (Rust)   │
│                 │         │                 │         │                 │
│  - Session list │         │  - Relay frames │         │  - Capture      │
│  - Live viewer  │         │  - Auth/JWT     │         │  - Input inject │
│  - Controls     │         │  - Session mgmt │         │  - Encoding     │
└─────────────────┘         └─────────────────┘         └─────────────────┘
                                    │
                                    │
                                    ▼
                            ┌─────────────────┐
                            │   PostgreSQL    │
                            │   (Sessions,    │
                            │    Audit Log)   │
                            └─────────────────┘
```

### Components

#### 1. Agent (Rust - Windows)
**Location:** `~/claude-projects/guru-connect/agent/`

Runs on Windows client machines to capture screen and inject input.

**Responsibilities:**
- Screen capture via DXGI (with GDI fallback)
- Frame encoding (Raw+Zstd, VP9, H264)
- Dirty rectangle detection
- Mouse/keyboard input injection
- WebSocket client connection to server

#### 2. Server (Rust + Axum)
**Location:** `~/claude-projects/guru-connect/server/`

Relay server that brokers connections between dashboard and agents.

**Responsibilities:**
- WebSocket relay for screen frames and input
- JWT authentication for dashboard users
- API key authentication for agents
- Session management and tracking
- Audit logging
- Database persistence

#### 3. Dashboard (React)
**Location:** `~/claude-projects/guru-connect/dashboard/`

Web-based viewer interface, to be integrated into GuruRMM dashboard.

**Responsibilities:**
- Live video stream display
- Mouse/keyboard event capture
- Session controls (pause, record, etc.)
- Quality/encoding settings
- Connection status

#### 4. Protocol Definitions (Protobuf)
**Location:** `~/claude-projects/guru-connect/proto/`

Shared message definitions for efficient serialization.

**Key Message Types:**
- `VideoFrame` - Screen frames (raw+zstd, VP9, H264)
- `MouseEvent` - Mouse input (click, move, scroll)
- `KeyEvent` - Keyboard input
- `SessionRequest/Response` - Session management

---

## Encoding Strategy

GuruConnect dynamically selects encoding based on network conditions and GPU availability:

| Scenario | Encoding | Target | Notes |
|----------|----------|--------|-------|
| LAN (<20ms RTT) | Raw BGRA + Zstd | <50ms latency | Dirty rectangles only |
| WAN + GPU | H264 hardware | 100-500 Kbps | NVENC/QuickSync |
| WAN - GPU | VP9 software | 200-800 Kbps | CPU encoding |

### Implementation Details

**DXGI Screen Capture:**
- Desktop Duplication API for Windows 8+
- Dirty region tracking (only changed areas)
- Fallback to GDI BitBlt for Windows 7

**Compression:**
- Zstd for lossless (LAN scenarios)
- VP9 for high-quality software encoding
- H264 for GPU-accelerated encoding

**Frame Rate Adaptation:**
- Target 30 FPS for active sessions
- Drop to 5 FPS when idle
- Skip frames if network buffer full

---

## Security Model

### Authentication

**Dashboard Users:** JWT tokens
- Login via GuruRMM credentials
- Tokens expire after 24 hours
- Refresh tokens for long sessions

**Agents:** API keys
- Pre-registered API key per agent
- Tied to machine ID in GuruRMM database
- Rotatable via admin panel

### Transport Security

**TLS Required:** All WebSocket connections use WSS (TLS)
- Certificate validation enforced
- Self-signed certs rejected in production
- SNI support for multi-tenant hosting

### Session Audit

**Logged Events:**
- Session start/end with user and machine IDs
- Connection duration and data transfer
- User actions (mouse clicks, keystrokes - aggregate only)
- Quality/encoding changes
- Recording start/stop (Phase 4)

**Retention:** 90 days in PostgreSQL

---

## Phase 1 MVP Goals

### Completed Features
- [x] Project structure and build system
- [x] Protocol Buffers definitions
- [x] Basic WebSocket relay server
- [x] DXGI screen capture implementation

### In Progress
- [ ] GDI fallback for screen capture
- [ ] Raw + Zstd encoding with dirty rectangles
- [ ] Mouse and keyboard input injection
- [ ] React viewer component
- [ ] Session management API

### Future Phases
- **Phase 2:** VP9 and H264 encoding
- **Phase 3:** GuruRMM dashboard integration
- **Phase 4:** Session recording and playback
- **Phase 5:** File transfer and clipboard sync
- **Phase 6:** Multi-monitor support

---

## Development

### Prerequisites

**Rust:** 1.75+ (install via rustup)
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

**Windows SDK:** For agent development
- Visual Studio 2019+ with C++ tools
- Windows 10 SDK

**Protocol Buffers Compiler:**
```bash
# macOS
brew install protobuf

# Windows (via Chocolatey)
choco install protoc

# Linux
apt-get install protobuf-compiler
```

### Build Commands

```bash
# Build all components (from workspace root)
cd ~/claude-projects/guru-connect
cargo build --release

# Build agent only
cargo build -p guruconnect-agent --release

# Build server only
cargo build -p guruconnect-server --release

# Run tests
cargo test

# Check for warnings
cargo clippy
```

### Cross-Compilation

Building Windows agent from Linux:

```bash
# Install Windows target
rustup target add x86_64-pc-windows-msvc

# Build (requires cross or appropriate linker)
cross build -p guruconnect-agent --target x86_64-pc-windows-msvc --release

# Alternative: Use GitHub Actions for Windows builds
```

---

## Running in Development

### Server

```bash
# Development mode
cargo run -p guruconnect-server

# With environment variables
export DATABASE_URL=postgres://user:pass@localhost/guruconnect
export JWT_SECRET=your-secret-key-here
export RUST_LOG=debug
cargo run -p guruconnect-server

# Production build
./target/release/guruconnect-server --bind 0.0.0.0:8443
```

### Agent

Agent must run on Windows:

```powershell
# Run from Windows
.\target\release\guruconnect-agent.exe

# With custom server URL
.\target\release\guruconnect-agent.exe --server wss://guruconnect.azcomputerguru.com
```

### Dashboard

```bash
cd dashboard
npm install
npm run dev

# Production build
npm run build
```

---

## Configuration

### Server Config

**Environment Variables:**
```bash
DATABASE_URL=postgres://guruconnect:password@localhost:5432/guruconnect
JWT_SECRET=<generate-random-256-bit-secret>
BIND_ADDRESS=0.0.0.0:8443
TLS_CERT=/path/to/cert.pem
TLS_KEY=/path/to/key.pem
LOG_LEVEL=info
```

### Agent Config

**Command-Line Flags:**
```
--server <url>           Server WebSocket URL (wss://...)
--api-key <key>          Agent API key for authentication
--quality <low|med|high> Default quality preset
--log-level <level>      Logging verbosity
```

**Registry Settings (Windows):**
```
HKLM\SOFTWARE\GuruConnect\Server = wss://guruconnect.azcomputerguru.com
HKLM\SOFTWARE\GuruConnect\ApiKey = <api-key>
```

---

## Deployment

### Server Deployment

**Recommended:** Docker container on GuruRMM server (172.16.3.30)

```yaml
# docker-compose.yml
version: '3.8'
services:
  guruconnect:
    image: guruconnect-server:latest
    ports:
      - "8443:8443"
    environment:
      DATABASE_URL: postgres://guruconnect:${DB_PASS}@db:5432/guruconnect
      JWT_SECRET: ${JWT_SECRET}
    volumes:
      - ./certs:/certs:ro
    depends_on:
      - db
```

### Agent Deployment

**Method 1:** GuruRMM Agent Integration
- Bundle with GuruRMM agent installer
- Auto-start via Windows service
- Managed API key provisioning

**Method 2:** Standalone MSI Installer
- Separate install package
- Manual API key configuration
- Service registration

---

## Monitoring and Logs

### Server Logs

```bash
# View real-time logs
docker logs -f guruconnect-server

# Check error rate
grep ERROR /var/log/guruconnect/server.log | wc -l
```

### Agent Logs

**Location:** `C:\ProgramData\GuruConnect\Logs\agent.log`

**Key Metrics:**
- Frame capture rate
- Encoding latency
- Network send buffer usage
- Connection errors

### Session Metrics

**Database Query:**
```sql
SELECT
    machine_id,
    user_id,
    AVG(duration_seconds) as avg_duration,
    SUM(bytes_transferred) as total_data
FROM sessions
WHERE created_at > NOW() - INTERVAL '7 days'
GROUP BY machine_id, user_id;
```

---

## Testing

### Unit Tests

```bash
# Run all unit tests
cargo test

# Test specific module
cargo test --package guruconnect-agent --lib capture
```

### Integration Tests

```bash
# Start test server
cargo run -p guruconnect-server -- --bind 127.0.0.1:8444

# Run agent against test server
cargo run -p guruconnect-agent -- --server ws://127.0.0.1:8444

# Dashboard tests
cd dashboard && npm test
```

### Performance Testing

```bash
# Measure frame capture latency
cargo bench --package guruconnect-agent

# Network throughput test
iperf3 -c <server> -p 8443
```

---

## Troubleshooting

### Agent Cannot Connect

**Check:**
1. Server URL correct? `wss://guruconnect.azcomputerguru.com`
2. API key valid? Check GuruRMM admin panel
3. Firewall blocking? Test: `telnet <server> 8443`
4. TLS certificate valid? Check browser: `https://<server>:8443/health`

**Logs:**
```powershell
Get-Content C:\ProgramData\GuruConnect\Logs\agent.log -Tail 50
```

### Black Screen in Viewer

**Common Causes:**
1. DXGI capture failed, no GDI fallback
2. Encoding errors (check agent logs)
3. Network packet loss (check quality)
4. Agent service stopped

**Debug:**
```powershell
# Check agent service
Get-Service GuruConnectAgent

# Test screen capture manually
.\guruconnect-agent.exe --test-capture
```

### High CPU Usage

**Possible Issues:**
1. Software encoding (VP9) on weak CPU
2. Full-screen capture when dirty rects should be used
3. Too high frame rate for network conditions

**Solutions:**
- Enable H264 hardware encoding (if GPU available)
- Lower quality preset
- Reduce frame rate to 15 FPS

---

## Key References

**RustDesk Source:**
`~/claude-projects/reference/rustdesk/`

**GuruRMM:**
`~/claude-projects/gururmm/` and `D:\ClaudeTools\projects\msp-tools\guru-rmm\`

**Development Plan:**
`~/.claude/plans/shimmering-wandering-crane.md`

**Session Logs:**
`~/claude-projects/session-logs/2025-12-21-guruconnect-session.md`

---

## Integration with GuruRMM

### Dashboard Integration

GuruConnect viewer will be embedded in GuruRMM dashboard:

```jsx
// Example React component integration
import { GuruConnectViewer } from '@guruconnect/react';

function MachineDetails({ machineId }) {
  return (
    <div>
      <h2>Machine: {machineId}</h2>
      <GuruConnectViewer
        machineId={machineId}
        apiToken={userToken}
      />
    </div>
  );
}
```

### API Integration

**Start Session:**
```http
POST /api/sessions/start
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "machine_id": "abc-123-def",
  "quality": "medium"
}
```

**Response:**
```json
{
  "session_id": "sess_xyz789",
  "websocket_url": "wss://guruconnect.azcomputerguru.com/ws/sess_xyz789"
}
```

---

## Roadmap

### Phase 1: MVP (In Progress)
- Basic screen capture and viewing
- Mouse/keyboard input
- Simple quality control

### Phase 2: Production Ready
- VP9 and H264 encoding
- Adaptive quality
- Connection recovery
- Performance optimization

### Phase 3: GuruRMM Integration
- Embedded dashboard viewer
- Single sign-on
- Unified session management
- Audit integration

### Phase 4: Advanced Features
- Session recording and playback
- Multi-monitor support
- Audio streaming
- Clipboard sync

### Phase 5: Enterprise Features
- Permission management
- Session sharing (invite technician)
- Chat overlay
- File transfer

---

## Project History

**2025-12-21:** Initial project planning and architecture design
**2025-12-21:** Build system setup, basic agent structure
**2026-01-XX:** Phase 1 MVP development ongoing

---

## License & Credits

**License:** Proprietary (Arizona Computer Guru internal use)

**Credits:**
- Architecture inspired by RustDesk
- Built with Rust, Tokio, Axum
- WebRTC considered but rejected (complexity)

---

## Support

**Technical Contact:** Mike Swanson
**Email:** mike@azcomputerguru.com
**Phone:** 520.304.8300

---

**Status:** Active Development - Phase 1 MVP
**Priority:** Medium (supporting GuruRMM platform)
**Next Milestone:** Complete dirty rectangle detection and input injection