Plataforma empresarial centralizada de backup y sincronización para entornos Windows sobre infraestructura Proxmox VE (Contenedores LXC Debian 12/13).

🚀 Arquitectura General

       ┌────────────────────────────────────────────────────────┐
       │             CLIENTES WINDOWS (10/11/Server)            │
       │                                                        │
       │  [ Agente PyQt6 / System Tray (.EXE) ]                 │
       │  ├── Selector visual de carpetas (QFileDialog)         │
       │  ├── Detección de bloqueos SQL Server (Locks/Growth)   │
       │  ├── Motor de Chunks (Bloques de 4MB con reanudación)  │
       │  └── Verificación de integridad SHA-256 local          │
       └──────────────────────────┬─────────────────────────────┘
                                  │ HTTPS / TLS (Chunks + JSON)
                                  ▼
       ┌────────────────────────────────────────────────────────┐
       │             SERVIDOR PROXMOX VE (LXC Debian)           │
       │                                                        │
       │  [ Nginx Proxy Inverso + SSL / Let's Encrypt ]         │
       │  ├── Frontend Web Dashboard (React 19 + TypeScript)    │
       │  ├── Backend REST API (FastAPI Asíncrono)              │
       │  ├── WebSockets (Telemetría de subidas en tiempo real) │
       │  ├── Ensamblado Streaming SHA-256 (Bajo consumo RAM)   │
       │  ├── Políticas de Retención (Diaria/Semanal/Mensual)   │
       │  └── Base de Datos (PostgreSQL 16 / SQLite dev)        │
       └────────────────────────────────────────────────────────┘

🔄 Flujo de Trabajo (Workflow) y Resolución del Problema

OnEver Drive está diseñado específicamente para resolver la necesidad de programar y monitorear backups en clientes fuera de la red local (a través de Internet) mediante una consola de gestión web centralizada ejecutada en una VM Linux.

🌐 Conectividad a través de Internet (Sin VPN)

El agente de Windows no requiere de red local ni VPN para comunicarse con el servidor central. Toda la comunicación (Handshake, Sincronización de Tareas, Subida de Chunks e Historial de Ejecuciones) se realiza a través de HTTPS/TLS (puerto 443) con seguridad criptográfica robusta:

Cada agente posee un par único de device_id y device_token permanente que se valida en el backend mediante un middleware de seguridad.

📦 Distribución del Agente "MeshCentral-Style" (Compilación y Enrolamiento)

Para facilitar el despliegue masivo y sencillo en clientes remotos:

Compilación Centralizada: El administrador puede empaquetar y generar el binario del agente directamente con el script de compilación windows-agent/build_exe.py (generando un archivo ejecutable portable de un solo archivo OnEverDriveAgent-Standalone.exe).
Enrolamiento por Código: Al igual que en MeshCentral, el administrador genera un Código de Registro Único (ej: OED-5752-EFED) con duración temporal (24 horas) en la interfaz web del servidor.
Handshake Seguro: El instalador del Agente de Windows se ejecuta en la máquina cliente, solicita este código y realiza una solicitud inicial segura. El servidor asocia la máquina al registro y devuelve un token exclusivo, vinculando el cliente de por vida.

📊 Diagrama de Secuencia del Flujo de Trabajo

sequenceDiagram
    autonumber
    actor Admin as Administrador Web
    participant Server as VM Linux (FastAPI + React)
    participant Agent as Agente Windows (en Internet)

    Note over Admin,Server: 1. Descarga y Vinculación (Estilo MeshCentral)
    Admin->>Server: Generar código de vinculación temporal (web)
    Server-->>Admin: Código temporal (Ej: OED-5752-EFED)
    Agent->>Server: Registro inicial con Código Temporal (HTTPS POST)
    Server-->>Agent: device_id y device_token seguro (Guardado en config.json)
    
    Note over Admin,Agent: 2. Sincronización de Configuración
    Admin->>Server: Crear/Editar Trabajo (Filtros, Cron, Copia Local)
    Agent->>Server: Consultar trabajos asignados (HTTPS GET)
    Server-->>Agent: Retorna configuración del Trabajo
    Agent->>Agent: Guarda/Actualiza config.json local

    Note over Agent,Server: 3. Ejecución de Tarea y Sincronización
    Agent->>Agent: Evalúa is_job_due (Planificador Cron / Proxmox)
    Agent->>Server: Iniciar sesión de corrida (POST /runs/start)
    Server-->>Agent: Retorna run_id
    Agent->>Agent: Copia Local Duplicada Robusta (.tmp -> original)
    Agent->>Server: Sube archivos por Chunks de 4MB (HTTPS)
    Agent->>Server: Reporta métricas finales y estado (POST /runs/{id}/complete)
    
    Note over Admin,Server: 4. Auditoría
    Admin->>Server: Abre modal "Historial de Ejecuciones" (React)
    Server-->>Admin: Muestra estadísticas de la corrida (eficiencia, errores, MBs)

📦 Estructura del Repositorio

backend/: API REST FastAPI con autenticación JWT, registro de dispositivos por código temporal, motor de chunks con reanudación, políticas de retención y WebSockets.
frontend/: Dashboard web moderno (Vite + React 19 + TypeScript) con telemetría en vivo, gestión de clientes, creación de trabajos y explorador de restauración.
windows-agent/: Agente nativo en PyQt6 para Windows con System Tray, selector de carpetas, notificaciones discretas y empaquetado en binario .exe (PyInstaller).
deployment/: Scripts de aprovisionamiento automatizado en contenedores nativos Debian 12/13 LXC en Proxmox VE, configuración de Nginx, SSL y mantenimiento de backups.
docs/: Documentación técnica, manual del agente Windows, arquitectura del motor de chunks y guía de despliegue en Proxmox.
tests/: Suite automatizada con Pytest para verificar reanudación ante microcortes, aislamiento de clientes y detección de bloqueos.

🧪 Ejecución Local para Desarrollo y Pruebas

Para depurar y probar la aplicación en tu máquina local:

Backend (FastAPI)

cd backend
# 1. Crear y activar entorno virtual
python -m venv venv
# Windows: venv\Scripts\activate
# Linux/Mac: source venv/bin/activate

# 2. Instalar dependencias
pip install -r requirements.txt

# 3. Ejecutar servidor en modo desarrollo
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Frontend (React + Vite)

cd frontend
# 1. Instalar dependencias
npm install

# 2. Iniciar servidor de desarrollo
npm run dev

🛠️ Requisitos de Despliegue en Proxmox VE

El backend y frontend se despliegan en un Contenedor LXC Debian 12/13 sin dependencias de Docker:

# 1. Crear el contenedor en el host Proxmox
bash deployment/proxmox/01-create-lxc-pve-host.sh

# 2. Instalar el entorno, PostgreSQL, Nginx y Backend dentro del LXC
pct enter 100
bash /root/deployment/proxmox/02-install-backend-debian.sh

# 3. Configurar certificados SSL
bash /root/deployment/proxmox/03-configure-ssl.sh

💻 Agente de Windows (.EXE)

El agente se ejecuta en el área de notificaciones (System Tray) y cuenta con una interfaz gráfica en PyQt6 para apuntar al servidor y seleccionar las carpetas locales:

# Ejecutar agente desde binario compilado
windows-agent\dist\OnEverDriveAgent-Standalone.exe

# O compilar nuevamente desde el código fuente
python windows-agent/build_exe.py

# Código de Registro Único
OED-5752-EFED

🔒 Seguridad y Multi-Inquilino

Aislamiento por Dispositivo: Cada máquina Windows tiene un device_id y device_token único generado criptográficamente.
Validación SHA-256: Cada bloque de 4MB y el archivo final ensamblado se verifican mediante streaming de hash SHA-256.
Protección SQL Server: Detección de archivos en uso para evitar transferencias incompletas de volcados .bak.

📝 Documentos y Cambios Recientes

Changelog: Consulta el Changelog de la Sesión para ver la lista completa de mejoras implementadas en la última sesión de desarrollo (sincronización bidireccional, planificación tipo Proxmox Backup Server y re-vinculación de agentes).
Visión Técnica / Roadmap: Consulta la Hoja de Ruta hacia Karen's Replicator para revisar el mapa de características y las fases de desarrollo propuestas.