# 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