# RedFlag Architecture Documentation

## Overview

RedFlag is a cross-platform update management system designed for homelab enthusiasts and self-hosters. It provides centralized visibility and control over software updates across multiple machines and platforms.

## System Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web Dashboard │    │   Server API    │    │   PostgreSQL    │
│   (React)       │◄──►│   (Go + Gin)    │◄──►│   Database      │
│   Port: 3001    │    │   Port: 8080    │    │   Port: 5432    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │   Agent Fleet   │
                    │   (Cross-platform) │
                    └─────────────────┘
                              │
                    ┌─────────┼─────────┐
                    ▼         ▼         ▼
            ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
            │ Linux Agent │ │Windows Agent│ │Docker Agent │
            │  (APT/DNF)  │ │ (Updates)   │ │ (Registry)  │
            └─────────────┘ └─────────────┘ └─────────────┘
```

## Core Components

### 1. Server Backend (`aggregator-server`)
- **Framework**: Go + Gin HTTP framework
- **Authentication**: JWT with refresh token system
- **API**: RESTful API with comprehensive endpoints
- **Database**: PostgreSQL with event sourcing architecture

#### Key Endpoints
```
POST /api/v1/agents/register
POST /api/v1/agents/renew
GET  /api/v1/agents
GET  /api/v1/agents/{id}/updates
POST /api/v1/updates/{id}/approve
POST /api/v1/updates/{id}/install
GET  /api/v1/updates
GET  /api/v1/commands
```

### 2. Agent System (`aggregator-agent`)
- **Language**: Go (single binary, cross-platform)
- **Architecture**: Universal agent with platform-specific scanners
- **Check-in Interval**: 5 minutes with jitter
- **Local Features**: CLI commands, offline capability

#### Supported Platforms
- **Linux**: APT (Debian/Ubuntu), DNF (Fedora/RHEL), Docker
- **Windows**: Windows Updates, Winget Package Manager
- **Cross-platform**: Docker containers on all platforms

### 3. Web Dashboard (`aggregator-web`)
- **Framework**: React with TypeScript
- **UI**: Real-time dashboard with agent status
- **Features**: Update approval, installation monitoring, system metrics
- **Authentication**: JWT-based with secure token handling

## Database Schema

### Core Tables
```sql
-- Agents register and maintain state
agents (id, hostname, os, architecture, metadata, created_at, updated_at)

-- Updates discovered by agents
updates (id, agent_id, package_name, package_type, current_version,
         available_version, severity, metadata, status, created_at)

-- Commands sent to agents
commands (id, agent_id, update_id, command_type, parameters,
         status, created_at, completed_at)

-- Secure refresh token authentication
refresh_tokens (id, agent_id, token_hash, expires_at, created_at,
               last_used_at, revoked)

-- Audit trail for all operations
logs (id, agent_id, level, message, metadata, created_at)
```

## Security Architecture

### Authentication System
- **Access Tokens**: 24-hour lifetime for API operations
- **Refresh Tokens**: 90-day sliding window for agent continuity
- **Token Storage**: SHA-256 hashed tokens in database
- **Sliding Window**: Active agents never expire, inactive agents auto-expire

### Security Features
- Cryptographically secure token generation
- Token revocation support
- Complete audit trails
- Rate limiting capabilities
- Secure agent registration with system verification

## Agent Communication Flow

```
1. Agent Registration
   Agent → POST /api/v1/agents/register → Server
   ← Access Token + Refresh Token ←

2. Periodic Check-in (5 minutes)
   Agent → GET /api/v1/commands (with token) → Server
   ← Pending Commands ←

3. Update Reporting
   Agent → POST /api/v1/updates (scan results) → Server
   ← Confirmation ←

4. Token Renewal (when needed)
   Agent → POST /api/v1/agents/renew (refresh token) → Server
   ← New Access Token ←
```

## Update Management Flow

```
1. Discovery Phase
   Agent scans local system → Updates detected → Reported to server

2. Approval Phase
   Admin reviews updates in dashboard → Approves updates →
   Commands created for agents

3. Installation Phase
   Agent receives commands → Installs updates → Reports results
   → Status updated in database

4. Verification Phase
   Server verifies installation success → Update status marked complete
   → Audit trail updated
```

## Local Agent Features

The agent provides value even without server connectivity:

### CLI Commands
```bash
# Local scan with results
sudo ./aggregator-agent --scan

# Show agent status and last scan
./aggregator-agent --status

# Detailed update list
./aggregator-agent --list-updates

# Export for automation
sudo ./aggregator-agent --scan --export=json > updates.json
```

### Local Cache
- **Location**: `/var/lib/aggregator/last_scan.json` (Linux)
- **Windows**: `C:\ProgramData\RedFlag\last_scan.json`
- **Features**: Offline viewing, status tracking, export capabilities

## Scanner Architecture

### Package Managers Supported
- **APT**: Debian/Ubuntu systems
- **DNF**: Fedora/RHEL systems
- **Docker**: Container image updates via Registry API
- **Windows Updates**: Native Windows Update integration
- **Winget**: Windows Package Manager

### Scanner Factory Pattern
```go
type Scanner interface {
    ScanForUpdates() ([]UpdateReportItem, error)
    GetInstaller() Installer
}

// Dynamic scanner selection based on platform
func GetScannersForPlatform() []Scanner {
    // Returns appropriate scanners for current platform
}
```

## Installation System

### Installer Factory Pattern
```go
type Installer interface {
    Install(update UpdateReportItem, dryRun bool) error
    GetInstalledVersion() (string, error)
}

// Automatic installer selection based on package type
func GetInstaller(packageType string) Installer {
    // Returns appropriate installer for package type
}
```

### Installation Features
- **Dry Run**: Pre-installation verification
- **Dependency Resolution**: Automatic dependency handling
- **Progress Tracking**: Real-time installation progress
- **Rollback Support**: Installation failure recovery
- **Batch Operations**: Multiple package installation

## Proxmox Integration (Future)

Planned hierarchical management for Proxmox environments:
```
Proxmox Cluster
├── Node 1
│   ├── LXC 100 (Ubuntu + Docker)
│   │   ├── Container: nginx:latest
│   │   └── Container: postgres:16
│   └── LXC 101 (Debian)
└── Node 2
    └── LXC 200 (Ubuntu + Docker)
```

## Performance Considerations

### Scalability Features
- **Event Sourcing**: Complete audit trail with state reconstruction
- **Connection Pooling**: Efficient database connection management
- **Caching**: Docker registry response caching (5-minute TTL)
- **Batch Operations**: Bulk update processing
- **Async Processing**: Non-blocking command execution

### Resource Usage
- **Agent Memory**: ~10-20MB typical usage
- **Agent CPU**: Minimal impact, periodic scans
- **Database**: Optimized indexes for common queries
- **Network**: Efficient JSON payload compression

## Development Architecture

### Monorepo Structure
```
RedFlag/
├── aggregator-server/     # Go backend
├── aggregator-agent/      # Go agent (cross-platform)
├── aggregator-web/        # React dashboard
├── docs/                  # Documentation
└── docker-compose.yml     # Development environment
```

### Build System
- **Go**: Standard `go build` with cross-compilation
- **React**: Vite build system with TypeScript
- **Docker**: Multi-stage builds for production
- **Makefile**: Common development tasks

## Configuration Management

### Environment Variables
```bash
# Server Configuration
SERVER_HOST=0.0.0.0
SERVER_PORT=8080
DATABASE_URL=postgresql://...
JWT_SECRET=your-secret-key

# Agent Configuration
REDFLAG_SERVER_URL=http://localhost:8080
AGENT_CONFIG_PATH=/etc/aggregator/config.json

# Web Configuration
VITE_API_URL=http://localhost:8080/api/v1
```

### Configuration Files
- **Server**: `.env` file or environment variables
- **Agent**: `/etc/aggregator/config.json` (JSON format)
- **Web**: `.env` file with Vite prefixes

This architecture supports the project's goals of providing a comprehensive, cross-platform update management system for homelab and self-hosting environments.