# RedFlag Agent - Quick Reference Guide

## Key Files and Line Numbers

### Main Agent Entry Point
- **File**: `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/cmd/agent/main.go`
- **Main loop**: Lines 410-549
- **Command switch**: Lines 502-543
- **Agent initialization**: Lines 387-549

### MONOLITHIC Scan Handler (Key Target for Refactoring)
- **Function**: `handleScanUpdates()`
- **File**: `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/cmd/agent/main.go`
- **Lines**: 551-709 (159 lines - the monolith)

**Detailed scanner calls within handleScanUpdates**:
- APT Scanner: lines 559-574
- DNF Scanner: lines 576-592
- Docker Scanner: lines 594-610
- Windows Update Scanner: lines 612-628
- Winget Scanner: lines 630-646
- Error aggregation & reporting: lines 648-709

### Scanner Implementations

| Scanner | File | Lines | Key Methods |
|---------|------|-------|-------------|
| APT | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/scanner/apt.go` | 1-91 | IsAvailable (23-26), Scan (29-42) |
| DNF | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/scanner/dnf.go` | 1-157 | IsAvailable (23-26), Scan (29-43), determineSeverity (121-157) |
| Docker | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/scanner/docker.go` | 1-163 | IsAvailable (34-47), Scan (50-123), checkForUpdate (137-154) |
| Registry Client | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/scanner/registry.go` | 1-260 | GetRemoteDigest (62-88), fetchManifestDigest (166-216) |
| Windows Update | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/scanner/windows_wua.go` | 1-553 | IsAvailable (27-30), Scan (33-67), convertWUAUpdate (91-211) |
| Winget | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/scanner/winget.go` | 1-662 | IsAvailable (34-43), Scan (46-84), attemptWingetRecovery (533-576) |

### System Information

| Component | File | Lines | Purpose |
|-----------|------|-------|---------|
| System Info Structure | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/system/info.go` | 13-28 | SystemInfo struct |
| DiskInfo Structure | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/system/info.go` | 45-57 | Multi-disk support |
| GetSystemInfo | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/system/info.go` | 60-100+ | Detailed system collection |
| Report System Info | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/cmd/agent/main.go` | 1357-1407 | Report to server (hourly) |
| System Metrics (lightweight) | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/cmd/agent/main.go` | 429-444 | Every check-in |

### Command Handlers

| Command | Function | File | Lines |
|---------|----------|------|-------|
| scan_updates | handleScanUpdates | main.go | 551-709 |
| collect_specs | Not implemented | main.go | ~509 |
| dry_run_update | handleDryRunUpdate | main.go | 992-1105 |
| install_updates | handleInstallUpdates | main.go | 873-989 |
| confirm_dependencies | handleConfirmDependencies | main.go | 1108-1216 |
| enable_heartbeat | handleEnableHeartbeat | main.go | 1219-1291 |
| disable_heartbeat | handleDisableHeartbeat | main.go | 1294-1355 |
| reboot | handleReboot | main.go | 1410-1495 |

### Supporting Subsystems

| Subsystem | File | Purpose |
|-----------|------|---------|
| Local Cache | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/cache/local.go` | Cache scan results locally |
| API Client | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/client/client.go` | Server communication |
| Config Manager | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/config/config.go` | Configuration handling |
| Installers | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/installer/` | Package installation (apt, dnf, docker, windows, winget) |
| Display | `/home/memory/Desktop/Projects/RedFlag/aggregator-agent/internal/display/terminal.go` | Terminal output formatting |

---

## Architecture Issues Found

### Problem 1: Monolithic Orchestration
**Location**: `handleScanUpdates()` lines 551-709

**Issue**: All scanner execution tightly coupled in single function
- No abstraction for scanner lifecycle
- Repeated code pattern 5 times (once per scanner)
- Sequential execution (no parallelization)
- Mixed concerns (availability check + scan + error handling)

**Example**:
```go
// This pattern repeats 5 times
if aptScanner.IsAvailable() {
    updates, err := aptScanner.Scan()
    if err != nil {
        scanErrors = append(scanErrors, fmt.Sprintf("APT scan failed: %v", err))
    } else {
        allUpdates = append(allUpdates, updates...)
    }
}
```

### Problem 2: No Subsystem Health Tracking
**Current State**: Scanners report errors as plain strings

**Missing**: 
- Per-scanner status tracking
- Subsystem readiness indicators
- Individual scanner metrics
- Enable/disable individual scanners without code changes

### Problem 3: Storage and System Info Not Subsystemized
**Current State**: 
- System metrics collected at main loop level (lines 429-444)
- Full system info reported hourly (lines 417-425)
- No formal "system info subsystem"

**Needed**:
- Separate system info subsystem with its own lifecycle
- DiskInfo is modular (supports multiple disks) but not leveraged
- Storage subsystem could be independent

### Problem 4: Error Aggregation Model
**Current**: Strings accumulated and reported together (lines 648-677)

**Better Would Be**:
- Per-subsystem error types
- Error codes instead of string concatenation
- Proper error handling chains

---

## Subsystems Currently Included

The `scan_updates` command integrates 5 distinct subsystems:

1. **APT Package Scanner** (Linux Debian/Ubuntu)
   - Checks: `apt list --upgradable`
   - Severity: Based on repository name
   
2. **DNF Package Scanner** (Linux Fedora/RHEL)
   - Checks: `dnf check-update`
   - Severity: Complex logic based on package name & repo
   
3. **Docker Image Scanner** (Container images)
   - Lists running containers
   - Queries Docker Registry API v2
   - Compares local vs remote digests
   
4. **Windows Update Scanner** (Windows OS updates)
   - Uses Windows Update Agent (WUA) COM API
   - Extracts rich metadata (KB articles, CVEs, MSRC severity)
   
5. **Winget Scanner** (Windows applications)
   - Multiple fallback methods
   - Includes recovery/repair logic
   - Categorizes packages

### Not Part of scan_updates:

- System info collection (separate hourly process)
- Local caching (separate subsystem)
- Installation/update operations (separate handlers)
- Installer implementations (separate files)

---

## Refactoring Opportunities

### Quick Wins:
1. Extract scanner loop into `ScannerOrchestrator` interface
2. Use factory pattern to get available scanners
3. Implement per-scanner timeout handling
4. Add metrics/timing per scanner

### Major Refactors:
1. Create formal "ScanningSubsystem" with lifecycle management
2. Separate system info into its own subsystem with scheduled updates
3. Implement per-subsystem configuration and enable/disable toggles
4. Add subsystem health check endpoints

---

## Modularity Assessment

### Modular Components (Can be changed independently):
- Individual scanner files (apt.go, dnf.go, docker.go, etc.)
- Registry client (separate from Docker scanner)
- System info gathering (platform-specific splits)
- Installer implementations
- Local cache

### Monolithic Components (Tightly coupled):
- handleScanUpdates orchestration
- Command processing switch statement
- Main loop timer logic
- Error aggregation logic
- Reporting logic

### Verdict:
**Modules are modular, but orchestration is monolithic.**

The individual scanner implementations follow good modular patterns (separate files, common interface), but how they're orchestrated (the handleScanUpdates function) violates single responsibility principle and couples scanner management logic with business logic.