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>
2025-12-30 08:51:58 -07:00
parent 48076e12b0
commit 7df824c2ca
1 changed files with 167 additions and 84 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,117 +1,200 @@
-# GuruConnect
+# GuruConnect - Project Guidelines

-Remote desktop solution similar to ScreenConnect, integrated with GuruRMM.
+## Overview

-## Project Overview
-
-GuruConnect provides remote screen control and backstage tools for Windows systems.
-It's designed to be fast, secure, and enterprise-ready.
+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    │
-│   (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)
- `server/` - Relay server (Rust + Axum)
- `dashboard/` - Web viewer (React, to be integrated with GuruRMM)
- `proto/` - Protobuf protocol definitions
+### 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

-## 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)
- Windows SDK (for agent)
- protoc (Protocol Buffers compiler)
+## Security Rules

-### 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
-# Build all (from workspace root)
-cargo build --release
+# Build agent (Windows)
+cargo build -p guruconnect --release

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

-# Build server only
-cargo build -p guruconnect-server --release
+# Check version
+./guruconnect --version        # Short: 0.1.0-48076e1
+./guruconnect version-info     # Full details
 ```

-### Cross-compilation (Agent for Windows)
+## Database Schema

-From Linux build server:
-```bash
-# Install Windows target
-rustup target add x86_64-pc-windows-msvc
+### 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

-# Build (requires cross or appropriate linker)
-cross build -p guruconnect-agent --target x86_64-pc-windows-msvc --release
+### 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
 ```

-## 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
-# Development
-cargo run -p guruconnect-server
+### Agent Distribution
+- **Download URL:** https://connect.azcomputerguru.com/downloads/guruconnect.exe
+- **Auto-update:** Not yet implemented (future feature)

-# With environment variables
-DATABASE_URL=postgres://... JWT_SECRET=... cargo run -p guruconnect-server
-```
+## Issue Tracking

-### Testing the Agent
+Use Gitea issues: https://git.azcomputerguru.com/azcomputerguru/guru-connect/issues

-The agent must be run on Windows:
-```powershell
-# Run from Windows
-.\target\release\guruconnect-agent.exe
-```
+Reference issues in commits:
+- `Fixes #1` - Closes the issue
+- `Related to #1` - Links without closing

-## Protocol
+## Testing Checklist

-Uses Protocol Buffers for efficient message serialization.
-See `proto/guruconnect.proto` for message definitions.
-
-Key message types:
- `VideoFrame` - Screen frames (raw+zstd, VP9, H264)
- `MouseEvent` - Mouse input
- `KeyEvent` - Keyboard input
- `SessionRequest/Response` - Session management
-
-## Encoding Strategy
-
-| 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)
+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