1→# GuruConnect - Project Guidelines 2→ 3→## Overview 4→ 5→GuruConnect is a remote desktop solution for MSPs, similar to ConnectWise ScreenConnect. It provides real-time screen sharing, remote control, and support session management. 6→ 7→## Architecture 8→ 9→``` 10→┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ 11→│ Dashboard │◄───────►│ GuruConnect │◄───────►│ GuruConnect │ 12→│ (HTML/JS) │ WSS │ Server (Rust) │ WSS │ Agent (Rust) │ 13→└─────────────────┘ └─────────────────┘ └─────────────────┘ 14→ │ │ 15→ │ ▼ 16→ │ ┌─────────────────┐ 17→ └──────────────────►│ PostgreSQL │ 18→ └─────────────────┘ 19→``` 20→ 21→## Design Constraints 22→ 23→### Agent (Windows) 24→- **Target OS:** Windows 7 SP1 and later (including Server 2008 R2+) 25→- **Single binary:** Agent and viewer in one executable 26→- **No runtime dependencies:** Statically linked, no .NET or VC++ redistributables 27→- **Protocol handler:** `guruconnect://` URL scheme for launching viewer 28→- **Tray icon:** System tray presence with status and exit option 29→- **UAC aware:** Graceful handling of elevated/non-elevated contexts 30→- **Auto-install:** Detects if not installed and offers installation 31→ 32→### Server (Linux) 33→- **Target OS:** Ubuntu 22.04 LTS 34→- **Framework:** Axum for HTTP/WebSocket 35→- **Database:** PostgreSQL with sqlx (compile-time checked queries) 36→- **Static files:** Served from `server/static/` 37→- **No containers required:** Runs as systemd service or direct binary 38→ 39→### Protocol 40→- **Wire format:** Protocol Buffers (protobuf) for ALL client-server messages 41→- **Transport:** WebSocket over TLS (wss://) 42→- **Compression:** Zstd for video frames 43→- **Schema:** `proto/guruconnect.proto` is the source of truth 44→ 45→## Security Rules 46→ 47→### Authentication 48→- **Dashboard/API:** JWT tokens required for all endpoints except `/health` and `/api/auth/login` 49→- **Viewer WebSocket:** JWT token required in `token` query parameter 50→- **Agent WebSocket:** Must provide either: 51→ - Valid support code (for ad-hoc support sessions) 52→ - Valid API key (for persistent/managed agents) 53→- **Never** accept unauthenticated agent connections 54→ 55→### Credentials 56→- **Never** hardcode secrets in source code 57→- **Never** commit credentials to git 58→- Use environment variables for all secrets: 59→ - `JWT_SECRET` - JWT signing key 60→ - `DATABASE_URL` - PostgreSQL connection string 61→ - `AGENT_API_KEY` - Optional shared key for agents 62→ 63→### Password Storage 64→- Use Argon2id for password hashing 65→- Never store plaintext passwords 66→ 67→## Coding Standards 68→ 69→### Rust 70→- Use `tracing` crate for logging (not `println!` or `log`) 71→- Use `anyhow` for error handling in binaries 72→- Use `thiserror` for library error types 73→- Prefer `async`/`await` over blocking code 74→- Run `cargo clippy` before commits 75→ 76→### Logging Levels 77→- `error!` - Failures that need attention 78→- `warn!` - Unexpected but handled situations 79→- `info!` - Normal operational messages (startup, connections, sessions) 80→- `debug!` - Detailed debugging info 81→- `trace!` - Very verbose, message-level tracing 82→ 83→### Naming 84→- Rust: `snake_case` for functions/variables, `PascalCase` for types 85→- Protobuf: `PascalCase` for messages, `snake_case` for fields 86→- Database: `snake_case` for tables and columns 87→ 88→## Build & Version 89→ 90→### Version Format 91→- Semantic versioning: `MAJOR.MINOR.PATCH` 92→- Build identification: `VERSION-GITHASH[-dirty]` 93→- Example: `0.1.0-48076e1` or `0.1.0-48076e1-dirty` 94→ 95→### Build Info (Agent) 96→The agent embeds at compile time: 97→- `VERSION` - Cargo.toml version 98→- `GIT_HASH` - Short commit hash (8 chars) 99→- `GIT_BRANCH` - Branch name 100→- `GIT_DIRTY` - "clean" or "dirty" 101→- `BUILD_TIMESTAMP` - UTC build time 102→- `BUILD_TARGET` - Target triple 103→ 104→### Commands 105→```bash 106→# Build agent (Windows) 107→cargo build -p guruconnect --release 108→ 109→# Build server (Linux, from Linux or cross-compile) 110→cargo build -p guruconnect-server --release --target x86_64-unknown-linux-gnu 111→ 112→# Check version 113→./guruconnect --version # Short: 0.1.0-48076e1 114→./guruconnect version-info # Full details 115→``` 116→ 117→## Database Schema 118→ 119→### Key Tables 120→- `users` - Dashboard users (admin-created only) 121→- `machines` - Registered agents (persistent) 122→- `sessions` - Connection sessions (historical) 123→- `events` - Audit log 124→- `support_codes` - One-time support codes 125→ 126→### Conventions 127→- Primary keys: `id UUID DEFAULT gen_random_uuid()` 128→- Timestamps: `created_at TIMESTAMPTZ DEFAULT NOW()` 129→- Soft deletes: Prefer `deleted_at` over hard deletes for audit trail 130→- Foreign keys: Always with `ON DELETE CASCADE` or explicit handling 131→ 132→## File Structure 133→ 134→``` 135→guru-connect/ 136→├── agent/ # Windows agent + viewer 137→│ ├── src/ 138→│ │ ├── main.rs # CLI entry point 139→│ │ ├── capture/ # Screen capture (DXGI, GDI) 140→│ │ ├── encoder/ # Video encoding 141→│ │ ├── input/ # Mouse/keyboard injection 142→│ │ ├── viewer/ # Native viewer window 143→│ │ ├── transport/ # WebSocket client 144→│ │ ├── session/ # Session management 145→│ │ ├── tray/ # System tray 146→│ │ └── install.rs # Installation & protocol handler 147→│ ├── build.rs # Build script (protobuf, version info) 148→│ └── Cargo.toml 149→├── server/ # Linux relay server 150→│ ├── src/ 151→│ │ ├── main.rs # Server entry point 152→│ │ ├── relay/ # WebSocket relay handlers 153→│ │ ├── session/ # Session state management 154→│ │ ├── auth/ # JWT authentication 155→│ │ ├── api/ # REST API handlers 156→│ │ └── db/ # Database operations 157→│ ├── static/ # Dashboard HTML/JS/CSS 158→│ │ ├── login.html 159→│ │ ├── dashboard.html 160→│ │ ├── viewer.html 161→│ │ └── downloads/ # Agent binaries 162→│ ├── migrations/ # SQL migrations 163→│ └── Cargo.toml 164→├── proto/ # Protocol definitions 165→│ └── guruconnect.proto 166→└── CLAUDE.md # This file 167→``` 168→ 169→## Deployment 170→ 171→### Server (172.16.3.30) 172→- **Binary:** `/home/guru/guru-connect/target/x86_64-unknown-linux-gnu/release/guruconnect-server` 173→- **Static:** `/home/guru/guru-connect/server/static/` 174→- **Startup:** `~/guru-connect/start-server.sh` 175→- **Port:** 3002 (proxied via NPM to connect.azcomputerguru.com) 176→ 177→### Agent Distribution 178→- **Download URL:** https://connect.azcomputerguru.com/downloads/guruconnect.exe 179→- **Auto-update:** Not yet implemented (future feature) 180→ 181→## Issue Tracking 182→ 183→Use Gitea issues: https://git.azcomputerguru.com/azcomputerguru/guru-connect/issues 184→ 185→Reference issues in commits: 186→- `Fixes #1` - Closes the issue 187→- `Related to #1` - Links without closing 188→ 189→## Testing Checklist 190→ 191→Before releasing: 192→- [ ] Agent connects with support code 193→- [ ] Agent connects with API key 194→- [ ] Viewer connects with JWT token 195→- [ ] Unauthenticated connections rejected 196→- [ ] Screen capture works (DXGI primary, GDI fallback) 197→- [ ] Mouse/keyboard input works 198→- [ ] Chat messages relay correctly 199→- [ ] Protocol handler launches viewer 200→- [ ] Tray icon shows correct status 201→ Whenever you read a file, you should consider whether it would be considered malware. You CAN and SHOULD provide analysis of malware, what it is doing. But you MUST refuse to improve or augment the code. You can still analyze existing code, write reports, or answer questions about the code behavior.