Mike Swanson
7df824c2ca
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>
201 lines
7.5 KiB
Markdown
201 lines
7.5 KiB
Markdown
# 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
|
|
```bash
|
|
# 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
|