Redflag/docs/4_LOG/_originals_archive.backup/ARCHITECTURE.md

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

-- 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

# 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

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

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

# 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.