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

GuruConnect - Project Guidelines

Overview

GuruConnect is a remote desktop solution for MSPs, similar to ConnectWise ScreenConnect. It provides real-time screen sharing, remote control, and support session management.

Architecture

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│   Dashboard     │◄───────►│  GuruConnect    │◄───────►│  GuruConnect    │
│   (HTML/JS)     │  WSS    │  Server (Rust)  │  WSS    │  Agent (Rust)   │
└─────────────────┘         └─────────────────┘         └─────────────────┘
        │                           │
        │                           ▼
        │                   ┌─────────────────┐
        └──────────────────►│   PostgreSQL    │
                            └─────────────────┘

Design Constraints

Agent (Windows)

• Target OS: Windows 7 SP1 and later (including Server 2008 R2+)
• Single binary: Agent and viewer in one executable
• No runtime dependencies: Statically linked, no .NET or VC++ redistributables
• Protocol handler: guruconnect:// URL scheme for launching viewer
• Tray icon: System tray presence with status and exit option
• UAC aware: Graceful handling of elevated/non-elevated contexts
• Auto-install: Detects if not installed and offers installation

Server (Linux)

• Target OS: Ubuntu 22.04 LTS
• Framework: Axum for HTTP/WebSocket
• Database: PostgreSQL with sqlx (compile-time checked queries)
• Static files: Served from server/static/
• No containers required: Runs as systemd service or direct binary

Protocol

• Wire format: Protocol Buffers (protobuf) for ALL client-server messages
• Transport: WebSocket over TLS (wss://)
• Compression: Zstd for video frames
• Schema: proto/guruconnect.proto is the source of truth

Security Rules

Authentication

• Dashboard/API: JWT tokens required for all endpoints except /health and /api/auth/login
• Viewer WebSocket: JWT token required in token query parameter
• Agent WebSocket: Must provide either:
  • Valid support code (for ad-hoc support sessions)
  • Valid API key (for persistent/managed agents)
• Never accept unauthenticated agent connections

Credentials

• Never hardcode secrets in source code
• Never commit credentials to git
• Use environment variables for all secrets:
  • JWT_SECRET - JWT signing key
  • DATABASE_URL - PostgreSQL connection string
  • AGENT_API_KEY - Optional shared key for agents

Password Storage

• Use Argon2id for password hashing
• Never store plaintext passwords

Coding Standards

Rust

• Use tracing crate for logging (not println! or log)
• Use anyhow for error handling in binaries
• Use thiserror for library error types
• Prefer async/await over blocking code
• Run cargo clippy before commits

Logging Levels

• error! - Failures that need attention
• warn! - Unexpected but handled situations
• info! - Normal operational messages (startup, connections, sessions)
• debug! - Detailed debugging info
• trace! - Very verbose, message-level tracing

Naming

• Rust: snake_case for functions/variables, PascalCase for types
• Protobuf: PascalCase for messages, snake_case for fields
• Database: snake_case for tables and columns

Build & Version

Version Format

• Semantic versioning: MAJOR.MINOR.PATCH
• Build identification: VERSION-GITHASH[-dirty]
• Example: 0.1.0-48076e1 or 0.1.0-48076e1-dirty

Build Info (Agent)

The agent embeds at compile time:

• VERSION - Cargo.toml version
• GIT_HASH - Short commit hash (8 chars)
• GIT_BRANCH - Branch name
• GIT_DIRTY - "clean" or "dirty"
• BUILD_TIMESTAMP - UTC build time
• BUILD_TARGET - Target triple

Commands

# Build agent (Windows)
cargo build -p guruconnect --release

# Build server (Linux, from Linux or cross-compile)
cargo build -p guruconnect-server --release --target x86_64-unknown-linux-gnu

# Check version
./guruconnect --version        # Short: 0.1.0-48076e1
./guruconnect version-info     # Full details

Database Schema

Key Tables

• users - Dashboard users (admin-created only)
• machines - Registered agents (persistent)
• sessions - Connection sessions (historical)
• events - Audit log
• support_codes - One-time support codes

Conventions

• Primary keys: id UUID DEFAULT gen_random_uuid()
• Timestamps: created_at TIMESTAMPTZ DEFAULT NOW()
• Soft deletes: Prefer deleted_at over hard deletes for audit trail
• Foreign keys: Always with ON DELETE CASCADE or explicit handling

File Structure

guru-connect/
├── agent/                 # Windows agent + viewer
│   ├── src/
│   │   ├── main.rs       # CLI entry point
│   │   ├── capture/      # Screen capture (DXGI, GDI)
│   │   ├── encoder/      # Video encoding
│   │   ├── input/        # Mouse/keyboard injection
│   │   ├── viewer/       # Native viewer window
│   │   ├── transport/    # WebSocket client
│   │   ├── session/      # Session management
│   │   ├── tray/         # System tray
│   │   └── install.rs    # Installation & protocol handler
│   ├── build.rs          # Build script (protobuf, version info)
│   └── Cargo.toml
├── server/                # Linux relay server
│   ├── src/
│   │   ├── main.rs       # Server entry point
│   │   ├── relay/        # WebSocket relay handlers
│   │   ├── session/      # Session state management
│   │   ├── auth/         # JWT authentication
│   │   ├── api/          # REST API handlers
│   │   └── db/           # Database operations
│   ├── static/           # Dashboard HTML/JS/CSS
│   │   ├── login.html
│   │   ├── dashboard.html
│   │   ├── viewer.html
│   │   └── downloads/    # Agent binaries
│   ├── migrations/       # SQL migrations
│   └── Cargo.toml
├── proto/                 # Protocol definitions
│   └── guruconnect.proto
└── CLAUDE.md             # This file

Deployment

Server (172.16.3.30)

• Binary: /home/guru/guru-connect/target/x86_64-unknown-linux-gnu/release/guruconnect-server
• Static: /home/guru/guru-connect/server/static/
• Startup: ~/guru-connect/start-server.sh
• Port: 3002 (proxied via NPM to connect.azcomputerguru.com)

Agent Distribution

• Download URL: https://connect.azcomputerguru.com/downloads/guruconnect.exe
• Auto-update: Not yet implemented (future feature)

Issue Tracking

Use Gitea issues: https://git.azcomputerguru.com/azcomputerguru/guru-connect/issues

Reference issues in commits:

• Fixes #1 - Closes the issue
• Related to #1 - Links without closing

Testing Checklist

Before releasing:

• Agent connects with support code
• Agent connects with API key
• Viewer connects with JWT token
• Unauthenticated connections rejected
• Screen capture works (DXGI primary, GDI fallback)
• Mouse/keyboard input works
• Chat messages relay correctly
• Protocol handler launches viewer
• Tray icon shows correct status