Mike Swanson
75ce1c2fd5
Enhanced code review and frontend validation with intelligent triggers: Code Review Agent Enhancement: - Added Sequential Thinking MCP integration for complex issues - Triggers on 2+ rejections or 3+ critical issues - New escalation format with root cause analysis - Comprehensive solution strategies with trade-off evaluation - Educational feedback to break rejection cycles - Files: .claude/agents/code-review.md (+308 lines) - Docs: CODE_REVIEW_ST_ENHANCEMENT.md, CODE_REVIEW_ST_TESTING.md Frontend Design Skill Enhancement: - Automatic invocation for ANY UI change - Comprehensive validation checklist (200+ checkpoints) - 8 validation categories (visual, interactive, responsive, a11y, etc.) - 3 validation levels (quick, standard, comprehensive) - Integration with code review workflow - Files: .claude/skills/frontend-design/SKILL.md (+120 lines) - Docs: UI_VALIDATION_CHECKLIST.md (462 lines), AUTOMATIC_VALIDATION_ENHANCEMENT.md (587 lines) Settings Optimization: - Repaired .claude/settings.local.json (fixed m365 pattern) - Reduced permissions from 49 to 33 (33% reduction) - Removed duplicates, sorted alphabetically - Created SETTINGS_PERMISSIONS.md documentation Checkpoint Command Enhancement: - Dual checkpoint system (git + database) - Saves session context to API for cross-machine recall - Includes git metadata in database context - Files: .claude/commands/checkpoint.md (+139 lines) Decision Rationale: - Sequential Thinking MCP breaks rejection cycles by identifying root causes - Automatic frontend validation catches UI issues before code review - Dual checkpoints enable complete project memory across machines - Settings optimization improves maintainability Total: 1,200+ lines of documentation and enhancements Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
206 lines
9.6 KiB
Plaintext
206 lines
9.6 KiB
Plaintext
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→
|
|
|
|
<system-reminder>
|
|
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.
|
|
</system-reminder>
|