# GuruConnect Requirements

## Design Principles

1. **End-user simplicity** - One-click or code-based session joining
2. **Standalone capable** - Works independently, integrates with GuruRMM optionally
3. **Technician-centric** - Built for MSP workflows

---

## End-User Portal (connect.azcomputerguru.com)

### Unauthenticated View

When a user visits the portal without being logged in:

```
┌─────────────────────────────────────────────────────┐
│                                                     │
│              [Company Logo]                         │
│                                                     │
│         Enter your support code:                    │
│         ┌─────────────────────────┐                │
│         │      8 4 7 2 9 1        │                │
│         └─────────────────────────┘                │
│                                                     │
│              [ Connect ]                            │
│                                                     │
│  ─────────────────────────────────────────────────  │
│                                                     │
│  Instructions will appear here after clicking       │
│  Connect, based on your browser.                    │
│                                                     │
└─────────────────────────────────────────────────────┘
```

### Connection Flow

1. **User enters code** → Click "Connect"
2. **Server validates code** → Returns session info or error
3. **Attempt app launch** via custom protocol:
   - `guruconnect://session/{code}`
   - If app is installed, it launches and connects
4. **If app doesn't launch** (timeout ~3 seconds):
   - Auto-download small EXE (`GuruConnect-{code}.exe`)
   - Show browser-specific instructions

### Browser-Specific Instructions

Detect browser via User-Agent and show appropriate guidance:

**Chrome:**
> "Click the download in the bottom-left corner of your screen, then click 'Open'"
> [Screenshot of Chrome download bar]

**Firefox:**
> "Click 'Save File', then open your Downloads folder and double-click the file"
> [Screenshot of Firefox download dialog]

**Edge:**
> "Click 'Open file' in the download notification at the top of your screen"
> [Screenshot of Edge download prompt]

**Safari:**
> "Click the download icon in the toolbar, then double-click the file"
> [Screenshot of Safari downloads]

**Generic/Unknown:**
> "Your download should start automatically. Look for the file in your Downloads folder and double-click to run it."

### Custom Protocol Handler

**Protocol:** `guruconnect://`

**Format:** `guruconnect://session/{code}`

**Registration:**
- Permanent agent registers protocol handler on install
- One-time agent does NOT register (to avoid clutter)

**Behavior:**
- If registered: OS launches installed agent with session code
- If not registered: Browser shows "nothing happened" → triggers download fallback

### One-Time Session Agent (Temp/Support)

**Key Requirements:**
- Runs in **user space** - NO admin elevation required
- Downloads as `GuruConnect-{code}.exe` (code baked in)
- ~3-5MB executable
- Self-contained (no installer, no dependencies)
- Connects directly to session on launch
- Self-deletes after session ends (or on next reboot)

**Elevation Note:**
- Basic screen sharing works without admin
- Some features (input to elevated windows, UAC dialogs) need admin
- Show optional "Run as Administrator" button for full access

---

## Technician Dashboard (Logged-In View)

### Visual Style

Follow GuruRMM dashboard design:
- HSL CSS variables for theming (dark/light mode support)
- Sidebar navigation with lucide-react icons
- Card-based content areas
- Responsive layout (mobile hamburger menu)
- Consistent component library (Button, Card, Input)

### Navigation Structure

```
┌──────────────────────────────────────────────────────────────┐
│ ┌──────────┐                                                 │
│ │GuruConnect│                                                │
│ └──────────┘                                                 │
│                                                              │
│  [LIST] Support      ← Active temp sessions                      │
│  [COMPUTER] Access       ← Unattended/permanent sessions             │
│  [CONFIG] Build        ← Installer builder                         │
│  [GEAR] Settings     ← Preferences, groupings, appearance        │
│                                                              │
│ ─────────────                                                │
│  👤 Mike S.                                                  │
│     Admin                                                    │
│  [Sign out]                                                  │
└──────────────────────────────────────────────────────────────┘
```

### Support Tab (Active Temporary Sessions)

**Layout:**
```
┌─────────────────────────────────────────────────────────────────────┐
│ Support Sessions                        [ + Generate Code ]         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ▼ My Sessions (3)                                                  │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ 847291 │ John's PC │ Connected │ 00:15:32 │ [Join] [End]    │   │
│  │ 293847 │ Waiting   │ Pending   │ -        │ [Cancel]        │   │
│  │ 182736 │ Sarah-PC  │ Connected │ 00:45:10 │ [Join] [End]    │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ▼ Team Sessions (2)                      [Howard's sessions]       │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │ 928374 │ DESKTOP-A │ Connected │ 00:05:22 │ [View] [Join]   │   │
│  │ 746382 │ Laptop-01 │ Connected │ 01:20:15 │ [View]          │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ▶ Support Requests (1)                   [End-user initiated]      │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

**Features:**
- Sessions grouped by technician (own first, then team)
- Real-time status updates (WebSocket)
- Duration timer for active sessions
- Quick actions: Join, View (spectate), End, Cancel
- Support request queue from end-user tray icon requests

### Access Tab (Unattended/Permanent Sessions)

**Layout:**
```
┌─────────────────────────────────────────────────────────────────────┐
│ Access                    [SEARCH] [Search...]           [ + Build ]      │
├──────────────┬──────────────────────────────────────────────────────┤
│              │                                                      │
│ ▼ By Company │  All Machines by Company              1083 machines  │
│   (empty) 120│  ─────────────────────────────────────────────────── │
│   4 Paws    1│  ┌──────────────────────────────────────────────┐   │
│   ACG      10│  │ ● PC-FRONT01    │ Glaztech │ Win 11 │ Online │   │
│   Glaztech 224  │ ● SERVER-DC01   │ Glaztech │ Svr 22 │ Online │   │
│   AirPros   2│  │ ○ LAPTOP-SALES  │ Glaztech │ Win 10 │ 2h ago │   │
│   ...        │  │ ● WORKSTATION-3 │ ACG      │ Win 11 │ Online │   │
│              │  │ ...                                           │   │
│ ▶ By Site    │  └──────────────────────────────────────────────┘   │
│ ▶ By OS      │                                                      │
│ ▶ By Tag     │  ──────────────── Machine Detail ─────────────────  │
│              │  Name: PC-FRONT01                                    │
│ ──────────── │  Company: Glaztech Industries                        │
│ Smart Groups │  Site: Phoenix Office                                │
│ ──────────── │  OS: Windows 11 Pro (23H2)                          │
│  Attention  1│  User: jsmith                                        │
│  Online    847  IP: 192.168.1.45 / 72.194.62.4                     │
│  Offline 30d 241 Serial: 8XKJF93                                    │
│  Offline 1yr 238 Last Seen: Now                                     │
│  Outdated  516│                                                      │
│  Recent     5│  [ Connect ] [ Wake ] [ Tools ▼ ]                    │
│              │                                                      │
│ ▶ My Filters │                                                      │
│  + New Filter│                                                      │
└──────────────┴──────────────────────────────────────────────────────┘
```

**Left Sidebar - Groupings:**
- By Company (with counts, expandable)
- By Site
- By OS
- By Tag
- By Device Type
- Smart Groups (auto-generated)
- Custom Filters (user-created)

**Main Panel:**
- Machine list with status indicators (● online, ○ offline)
- Quick info columns (configurable)
- Click to select → shows detail panel

**Right Panel - Machine Detail:**
- Full machine info (Session, Device, Network sections)
- Action buttons: Connect, Wake (if offline), Tools dropdown

### Build Tab (Installer Builder)

**Layout:**
```
┌─────────────────────────────────────────────────────────────────────┐
│ Build Installer                                                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Name:        [ Use Machine Name        ▼ ]                         │
│  Company:     [ __________________________ ]    (autocomplete)      │
│  Site:        [ __________________________ ]    (autocomplete)      │
│  Department:  [ __________________________ ]                        │
│  Device Type: [ Workstation              ▼ ]                        │
│  Tag:         [ __________________________ ]                        │
│                                                                     │
│  Platform:    ○ Windows 64-bit (recommended)                        │
│               ○ Windows 32-bit                                      │
│               ○ Linux (coming soon)                                 │
│                                                                     │
│  ─────────────────────────────────────────────────────────────────  │
│                                                                     │
│  [ Download EXE ]  [ Download MSI ]  [ Copy URL ]  [ Send Link ]    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### Settings Tab

**Sections:**

**Appearance:**
- Theme: Light / Dark / System
- Sidebar: Expanded / Collapsed by default
- Default landing tab: Support / Access

**Groupings:**
- Default grouping for Access tab
- Show/hide specific smart groups
- Configure custom filter defaults

**Notifications:**
- Browser notifications: On/Off
- Sound alerts: On/Off
- Email alerts for support requests: On/Off

**Session Defaults:**
- Default session visibility: Private / Team / Company
- Auto-accept from specific companies

**Account:**
- Change password
- Two-factor authentication
- API keys (for integrations)

---

## Session Types

### 1. Support Sessions (Attended/One-Time)

**End-User Experience:**
- User visits portal (e.g., `support.azcomputerguru.com`)
- Portal generates a 5-6 digit numeric code (e.g., `847291`)
- User enters code OR clicks generated link
- Small executable downloads and runs (no install required)
- Session connects to assigned technician

**Technician Experience:**
- Generate session codes from dashboard
- Codes can be pre-assigned to specific tech or first-come
- Session appears on assigned tech's dashboard

**Code Management:**
- Codes remain active until used (no automatic expiration)
- Anti-collision: Active codes tracked in database, never reissued while active
- Once session completes, code is released back to pool
- Manual code cancellation available
- Optional: Tech can set manual expiration if desired
- 6 digits = 1M codes, plenty of headroom for concurrent active codes

### 2. Unattended Sessions (Permanent/MSP)

**Installer Builder:**

Build custom installers with pre-defined metadata fields:

| Field | Description | Example |
|-------|-------------|---------|
| Name | Machine identifier | "Use Machine Name" (auto) or custom |
| Company | Client/organization | "Glaztech Industries" |
| Site | Physical location | "Phoenix Office" |
| Department | Business unit | "Accounting" |
| Device Type | Machine category | "Workstation", "Server", "Laptop" |
| Tag | Custom label | "VIP", "Critical", "Testing" |

**Installer Output Options:**
- Download EXE directly
- Download MSI (for GPO deployment)
- Copy installer URL (for deployment scripts)
- Send link via email

**Server-Built Installers:**
- Server generates installers on-demand
- All metadata (Company, Site, etc.) baked into binary
- Unique installer per configuration
- No manual config file editing required
- Server URL and auth token embedded

**MSI Support:**
- MSI wrapper for Group Policy deployment
- Silent install support: `msiexec /i guruconnect.msi /qn`
- Uninstall via Add/Remove Programs or GPO
- Transform files (.mst) for custom configurations (optional)

**End-User Reconfiguration:**
- Re-run installer with flags to modify settings
- `--reconfigure` flag enters config mode instead of reinstall
- User can change: Name, Site, Tag, Department
- Changes sync to server on next check-in
- Useful for when machine moves to different site/department

Example:
```
guruconnect-agent.exe --reconfigure --site "New York Office" --tag "Laptop"
```

**Deployment:**
- Installed as Windows service
- Persists across reboots
- Auto-reconnects on network changes
- Can be bundled with GuruRMM agent OR standalone
- Metadata fields baked into agent at build time

**Management:**
- Assigned to client/site hierarchy
- Always available for remote access (when machine is on)
- Background service, no user interaction required

---

## Technician Dashboard

### Session Visibility & Permissions

| Role | Own Sessions | Team Sessions | All Sessions |
|------|--------------|---------------|--------------|
| Technician | Full access | View if permitted | No |
| Senior Tech | Full access | View + join | View |
| Admin | Full access | Full access | Full access |

**Permission Model:**
- Sessions created by a tech default to their dashboard
- Configurable visibility: Private, Team, Company-wide
- "Snoop" capability for supervisors (view session list, optionally join)
- Session handoff between technicians

### Auto-Generated Groups (Sidebar)

The dashboard automatically generates navigable groups based on metadata and status:

**By Metadata Field:**
- All Machines by Company (with counts per company)
- All Machines by Site
- All Machines by OS
- All Machines by Tag
- All Machines by Device Type

**Smart Status Groups:**
| Group | Definition |
|-------|------------|
| Attention | Machines flagged for follow-up |
| Host Connected | Tech currently connected |
| Guest Connected | End-user currently at machine |
| Recently Accessed | Connected within last 24 hours |
| Offline 30 Days | No check-in for 30+ days |
| Offline 1 Year | Stale agents, cleanup candidates |
| Outdated Clients | Agent version behind current |
| Powered on last 10 min | Just came online |

**Custom Session Groups:**
- Create saved filter combinations
- Name and organize custom groups
- Share groups with team (optional)

### Machine Detail Panel

When a machine is selected, show comprehensive info in side panel:

**Session Info:**
- Name, Company, Site, Department
- Device Type, Tag
- Hosts Connected (tech count)
- Guests Connected (user present)
- Guest Last Connected
- Logged On User
- Idle Time
- Pending Activity
- Custom Attributes

**Device Info:**
- Machine name
- Operating System + Version
- OS Install Date
- Processor
- Available Memory
- Manufacturer & Model
- Serial Number / Service Tag
- Machine Description

**Network Info:**
- Public IP Address
- Private IP Address(es)
- MAC Address(es)

**Other:**
- Agent Version
- Last Check-in
- First Seen
- Screenshot thumbnail (optional)

### Unattended Session Search

**Searchable Fields:**
- Hostname / Computer name
- Internal IP address
- External/Public IP address
- Currently logged-in user
- OS type (Windows 10, 11, Server 2019, etc.)
- OS version/build number
- Serial number
- Service tag (Dell, HP, Lenovo tags)
- Client/Site assignment
- Custom tags/labels
- Last check-in time
- Agent version

**Filter Capabilities:**
- Last check-in: < 1 hour, < 24 hours, < 7 days, > 30 days (stale)
- OS type grouping
- Client/Site hierarchy
- Online/Offline status
- Custom saved filters (user-defined queries)

**Saved Searches:**
- Create and name custom filter combinations
- Share saved searches with team
- Pin frequently used searches

---

## Remote Control Features

### Screen Control
- Real-time screen viewing
- Mouse control (click, drag, scroll)
- Keyboard input
- Multi-monitor support (switch displays, view all)

### Clipboard Integration

**Priority Feature - Full Bidirectional Clipboard:**

| Direction | Content Types |
|-----------|---------------|
| Local → Remote | Text, Files, Images, Rich text |
| Remote → Local | Text, Files, Images, Rich text |

**Special Capabilities:**
- **Keystroke injection from clipboard** - Paste local clipboard as keystrokes (for login screens, BIOS, pre-OS environments)
- Drag-and-drop file transfer
- Large file support (chunked transfer with progress)

### File Transfer
- Browse remote filesystem
- Upload files to remote
- Download files from remote
- Drag-and-drop support
- Transfer queue with progress

### Backstage Tools (No Screen Required)
- Remote command prompt / PowerShell
- Task manager view
- Services manager
- Registry editor (future)
- Event log viewer (future)
- System info panel

### Chat / Messaging

**Bidirectional Chat:**
- Tech can message end user during session
- End user can message tech
- Chat persists across session reconnects
- Chat history viewable in session log

**End-User Initiated Contact:**
- System tray icon for permanent agents
- "Request Support" option in tray menu
- User can type message/description of issue
- Creates support request visible to assigned technicians

**Technician Notifications:**
- Dashboard shows pending support requests
- Optional: Desktop/browser notifications for new requests
- Optional: Email/webhook alerts for after-hours requests
- Request queue with timestamps and user messages

### Credential Management (Future)

**Credential Injection:**
- Integration with ITGlue for credential lookup
- Integration with GuruRMM credential vault
- Tech selects credential from dropdown, never sees actual password
- Credential injected directly as keystrokes to remote session
- Audit log of which credential was used, by whom, when

**Local Credential Capture (Future):**
- Optional feature to capture credentials entered during session
- Stored encrypted, accessible only to admins
- For scenarios where client provides password verbally

---

## Security Requirements

### Authentication
- Technician login with username/password
- MFA/2FA support (TOTP)
- SSO integration (future - Azure AD, Google)
- API key auth for programmatic access

### Session Security
- All traffic over TLS/WSS
- End-to-end encryption for screen data
- Session consent prompt (attended sessions)
- Configurable session timeout

### Audit & Compliance
- Full audit log: who, when, what machine, duration
- Optional session recording
- Action logging (file transfers, commands run)
- Exportable audit reports

---

## Integration

### GuruRMM Integration
- Launch remote session from RMM agent list
- Share agent data (hostname, IP, user, etc.)
- Single authentication
- Unified dashboard option

### Standalone Mode
- Fully functional without GuruRMM
- Own user management
- Own agent deployment
- Can be licensed/sold separately

---

## Agent Requirements

### Support Session Agent (One-Time)
- Single executable, no installation
- Downloads and runs from portal
- Self-deletes after session ends
- Minimal footprint (<5MB)
- No admin rights required for basic screen share
- Admin rights optional for elevated access

### Unattended Agent (Permanent)
- Windows service installation
- Auto-start on boot
- Runs as SYSTEM for full access
- Configurable check-in interval
- Resilient reconnection

**Auto-Update:**
- Agent checks for updates on configurable interval
- Silent background update (no user interaction)
- Rollback capability if update fails
- Version reported to server for "Outdated Clients" filtering

**Lightweight Performance:**
- Minimal CPU/RAM footprint when idle
- No performance impact during normal operation
- Screen capture only active during remote session
- Target: <10MB RAM idle, <1% CPU idle

**Survival & Recovery:**
- Survives reboots (Windows service auto-start)
- Works in Safe Mode with Networking
- Registers as safe-mode-capable service
- Remote-initiated Safe Mode reboot (with networking)
- Auto-reconnects after safe mode boot

**Safe Mode Reboot Feature:**
- Tech can trigger safe mode reboot from dashboard
- Options: Safe Mode, Safe Mode with Networking, Safe Mode with Command Prompt
- Agent persists through safe mode boot
- Useful for malware removal, driver issues, repairs

**Emergency Reboot:**
- Force immediate reboot without waiting for processes
- Bypasses "program not responding" dialogs
- Equivalent to holding power button, but cleaner
- Use case: Frozen system, hung updates, unresponsive machine
- Confirmation required to prevent accidental use

**Wake-on-LAN:**
- Store MAC address for each agent
- Send WoL magic packet to wake offline machines
- Works within same broadcast domain (LAN)
- For remote WoL: requires WoL relay/proxy on local network
- Dashboard shows "Wake" button for offline machines with known MAC
- Optional: Integration with GuruRMM agent as WoL relay

### Reported Metrics (Unattended)
- Hostname
- Internal IP(s)
- External IP
- Current user
- OS type and version
- Serial number
- Service tag
- CPU, RAM, Disk (basic)
- Last boot time
- Agent version
- Custom properties (extensible)

---

## Platform Support

### Build Targets

| Target | Architecture | Priority | Notes |
|--------|--------------|----------|-------|
| `x86_64-pc-windows-msvc` | 64-bit | Primary | Default build, Win7+ |
| `i686-pc-windows-msvc` | 32-bit | Secondary | Legacy outliers |

### Phase 1 (MVP)
- Windows 10/11 agents (64-bit)
- Windows Server 2016+ agents (64-bit)
- Web dashboard (any browser)

### Phase 2
- 32-bit agent builds for legacy systems
- Windows 7/8.1 support

### Future Phases
- macOS agent
- Linux agent
- Mobile viewer (iOS/Android)

---

## Non-Functional Requirements

### Performance
- Screen updates: 30+ FPS on LAN, 15+ FPS on WAN
- Input latency: <100ms on LAN, <200ms on WAN
- Support 50+ concurrent unattended agents per server (scalable)

### Reliability
- Agent auto-reconnect on network change
- Server clustering for HA (future)
- Graceful degradation on poor networks

### Deployment
- Single binary server (Docker or native)
- Single binary agent (MSI installer + standalone EXE)
- Cloud-hostable or on-premises

---

## Team Feedback (2025-12-28)

### Howard's Requirements

#### Core Remote Support & Access Capabilities

1. **Screen Sharing & Remote Control**
   - View and interact with the end-user's desktop in real time
   - Technicians can control mouse and keyboard, just like sitting at the remote machine

2. **Attended & Unattended Access**
   - Attended support: on-demand support sessions where the user connects via a session code or link
   - Unattended access: persistent remote connections that allow access anytime without user presence

3. **Session Management**
   - Initiate, pause, transfer, and end remote sessions
   - Session transfer: pass control of a session to another technician
   - Session pause and idle timeout controls

4. **File & Clipboard Sharing**
   - Drag-and-drop file transfer between local and remote systems
   - Clipboard sharing for copy/paste between devices

5. **Multi-Session Handling**
   - Technicians can manage multiple concurrent remote sessions

6. **Multi-Monitor Support**
   - Seamlessly switch between multiple monitors on the remote system

#### Advanced Support & Administrative Functions

7. **Backstage / Silent Support Mode**
   - Execute tasks, run scripts, and troubleshoot without disrupting the user's screen (background session)

8. **Shared & Personal Toolboxes**
   - Save commonly used tools, scripts, or executables
   - Share them with team members for reuse in sessions

9. **Custom Scripts & Automation**
   - Automate repetitive tasks during remote sessions

10. **Diagnostic & Command Tools**
    - Run PowerShell, Command Prompt, view system event logs, uninstall apps, start/stop services, kill processes, etc.
    - Better PowerShell/CMD running abilities with configurable timeouts (checkboxes/text boxes instead of typing every time)

#### Security & Access Control Features

11. **Encryption**
    - All traffic is secured with AES-256 encryption

12. **Role-Based Permissions**
    - Create granular technician roles and permissions to control who can do what

13. **Two-Factor & Login Security**
    - Support for multi-factor authentication (MFA) and other secure login methodologies

14. **Session Consent & Alerts**
    - Require end-user consent before connecting (configurable)
    - Alerts notify users of maintenance or work in progress

15. **Audit Logs & Session Recording**
    - Automatically record sessions
    - Maintain detailed logs of connections and actions for compliance

#### Communication & Collaboration Tools

16. **Real-Time Chat**
    - Text chat between technician and end user during sessions

17. **Screen Annotations**
    - Draw and highlight areas on the user's screen for clearer instructions

#### Cross-Platform & Mobile Support

18. **Cross-Platform Support**
    - Remote control across Windows, macOS, Linux, iOS, and Android

19. **Mobile Technician Support**
    - Technicians can support clients from mobile devices (view screens, send Ctrl-Alt-Delete, reboot)

20. **Guest Mobile Support**
    - Remote assistance for user Android and iOS devices

#### Integration & Customization

21. **PSA & Ticketing Integrations**
    - Launch support sessions from RMM/PSA and other ticketing systems

22. **Custom Branding & Interface**
    - White-labeling, logos, colors, and custom client titles

23. **Machine Organization & Search**
    - Dynamic grouping of devices and custom property filtering to locate machines quickly

#### Reporting & Monitoring

24. **Session & System Reports**
    - Audit logs, session histories, technician performance data, etc.

25. **Diagnostic Reporting**
    - Collect performance and diagnostic information during or after sessions

### Additional Notes from Howard

- **64-bit client requirement** - ScreenConnect doesn't have a 64-bit client, which limits deployment options
- **PowerShell timeout controls** - Should have UI controls (checkboxes/text boxes) for timeouts rather than typing commands every time
