Add project guidelines (CLAUDE.md)
Documents architecture, design constraints, security rules, coding standards, and deployment procedures for GuruConnect. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
251
CLAUDE.md
251
CLAUDE.md
@@ -1,117 +1,200 @@
|
|||||||
# GuruConnect
|
# GuruConnect - Project Guidelines
|
||||||
|
|
||||||
Remote desktop solution similar to ScreenConnect, integrated with GuruRMM.
|
## Overview
|
||||||
|
|
||||||
## Project 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.
|
||||||
|
|
||||||
GuruConnect provides remote screen control and backstage tools for Windows systems.
|
|
||||||
It's designed to be fast, secure, and enterprise-ready.
|
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
```
|
```
|
||||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||||
│ Dashboard │◄───────►│ GuruConnect │◄───────►│ GuruConnect │
|
│ Dashboard │◄───────►│ GuruConnect │◄───────►│ GuruConnect │
|
||||||
│ (React) │ WSS │ Server (Rust) │ WSS │ Agent (Rust) │
|
│ (HTML/JS) │ WSS │ Server (Rust) │ WSS │ Agent (Rust) │
|
||||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ ┌─────────────────┐
|
||||||
|
└──────────────────►│ PostgreSQL │
|
||||||
|
└─────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
## Directory Structure
|
## Design Constraints
|
||||||
|
|
||||||
- `agent/` - Windows remote desktop agent (Rust)
|
### Agent (Windows)
|
||||||
- `server/` - Relay server (Rust + Axum)
|
- **Target OS:** Windows 7 SP1 and later (including Server 2008 R2+)
|
||||||
- `dashboard/` - Web viewer (React, to be integrated with GuruRMM)
|
- **Single binary:** Agent and viewer in one executable
|
||||||
- `proto/` - Protobuf protocol definitions
|
- **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
|
||||||
|
|
||||||
## Building
|
### 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
|
||||||
|
|
||||||
### Prerequisites
|
### 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
|
||||||
|
|
||||||
- Rust 1.75+ (install via rustup)
|
## Security Rules
|
||||||
- Windows SDK (for agent)
|
|
||||||
- protoc (Protocol Buffers compiler)
|
|
||||||
|
|
||||||
### Build Commands
|
### 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
|
||||||
```bash
|
```bash
|
||||||
# Build all (from workspace root)
|
# Build agent (Windows)
|
||||||
cargo build --release
|
cargo build -p guruconnect --release
|
||||||
|
|
||||||
# Build agent only
|
# Build server (Linux, from Linux or cross-compile)
|
||||||
cargo build -p guruconnect-agent --release
|
cargo build -p guruconnect-server --release --target x86_64-unknown-linux-gnu
|
||||||
|
|
||||||
# Build server only
|
# Check version
|
||||||
cargo build -p guruconnect-server --release
|
./guruconnect --version # Short: 0.1.0-48076e1
|
||||||
|
./guruconnect version-info # Full details
|
||||||
```
|
```
|
||||||
|
|
||||||
### Cross-compilation (Agent for Windows)
|
## Database Schema
|
||||||
|
|
||||||
From Linux build server:
|
### Key Tables
|
||||||
```bash
|
- `users` - Dashboard users (admin-created only)
|
||||||
# Install Windows target
|
- `machines` - Registered agents (persistent)
|
||||||
rustup target add x86_64-pc-windows-msvc
|
- `sessions` - Connection sessions (historical)
|
||||||
|
- `events` - Audit log
|
||||||
|
- `support_codes` - One-time support codes
|
||||||
|
|
||||||
# Build (requires cross or appropriate linker)
|
### Conventions
|
||||||
cross build -p guruconnect-agent --target x86_64-pc-windows-msvc --release
|
- 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
|
||||||
```
|
```
|
||||||
|
|
||||||
## Development
|
## Deployment
|
||||||
|
|
||||||
### Running the Server
|
### 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)
|
||||||
|
|
||||||
```bash
|
### Agent Distribution
|
||||||
# Development
|
- **Download URL:** https://connect.azcomputerguru.com/downloads/guruconnect.exe
|
||||||
cargo run -p guruconnect-server
|
- **Auto-update:** Not yet implemented (future feature)
|
||||||
|
|
||||||
# With environment variables
|
## Issue Tracking
|
||||||
DATABASE_URL=postgres://... JWT_SECRET=... cargo run -p guruconnect-server
|
|
||||||
```
|
|
||||||
|
|
||||||
### Testing the Agent
|
Use Gitea issues: https://git.azcomputerguru.com/azcomputerguru/guru-connect/issues
|
||||||
|
|
||||||
The agent must be run on Windows:
|
Reference issues in commits:
|
||||||
```powershell
|
- `Fixes #1` - Closes the issue
|
||||||
# Run from Windows
|
- `Related to #1` - Links without closing
|
||||||
.\target\release\guruconnect-agent.exe
|
|
||||||
```
|
|
||||||
|
|
||||||
## Protocol
|
## Testing Checklist
|
||||||
|
|
||||||
Uses Protocol Buffers for efficient message serialization.
|
Before releasing:
|
||||||
See `proto/guruconnect.proto` for message definitions.
|
- [ ] Agent connects with support code
|
||||||
|
- [ ] Agent connects with API key
|
||||||
Key message types:
|
- [ ] Viewer connects with JWT token
|
||||||
- `VideoFrame` - Screen frames (raw+zstd, VP9, H264)
|
- [ ] Unauthenticated connections rejected
|
||||||
- `MouseEvent` - Mouse input
|
- [ ] Screen capture works (DXGI primary, GDI fallback)
|
||||||
- `KeyEvent` - Keyboard input
|
- [ ] Mouse/keyboard input works
|
||||||
- `SessionRequest/Response` - Session management
|
- [ ] Chat messages relay correctly
|
||||||
|
- [ ] Protocol handler launches viewer
|
||||||
## Encoding Strategy
|
- [ ] Tray icon shows correct status
|
||||||
|
|
||||||
| Scenario | Encoding |
|
|
||||||
|----------|----------|
|
|
||||||
| LAN (<20ms RTT) | Raw BGRA + Zstd + dirty rects |
|
|
||||||
| WAN + GPU | H264 hardware |
|
|
||||||
| WAN - GPU | VP9 software |
|
|
||||||
|
|
||||||
## Key References
|
|
||||||
|
|
||||||
- RustDesk source: `~/claude-projects/reference/rustdesk/`
|
|
||||||
- GuruRMM: `~/claude-projects/gururmm/`
|
|
||||||
- Plan: `~/.claude/plans/shimmering-wandering-crane.md`
|
|
||||||
|
|
||||||
## Phase 1 MVP Goals
|
|
||||||
|
|
||||||
1. DXGI screen capture with GDI fallback
|
|
||||||
2. Raw + Zstd encoding with dirty rectangle detection
|
|
||||||
3. Mouse and keyboard input injection
|
|
||||||
4. WebSocket relay through server
|
|
||||||
5. Basic React viewer
|
|
||||||
|
|
||||||
## Security Considerations
|
|
||||||
|
|
||||||
- All connections use TLS
|
|
||||||
- JWT authentication for dashboard users
|
|
||||||
- API key authentication for agents
|
|
||||||
- Session audit logging
|
|
||||||
- Optional session recording (Phase 4)
|
|
||||||
|
|||||||
Reference in New Issue
Block a user