# OnEver Drive — Arquitectura Técnica y Especificación

## 1. Visión General
**OnEver Drive** es una plataforma de copia de seguridad y sincronización centralizada de nivel empresarial, diseñada para respaldar de manera desatendida y segura servidores y estaciones de trabajo Windows hacia un cluster de virtualización **Proxmox VE**.

La plataforma divide responsabilidades en dos capas desacopladas:
1. **Backend API + Interfaz Web Centralizada**: Administra clientes, define trabajos de respaldo, supervisa telemetría en tiempo real y ejecuta políticas de retención.
2. **Agente Windows (Servicio de Fondo)**: Detecta cambios en carpetas locales, valida estabilidad y bloqueo de archivos (especialmente volcados masivos `.bak` de Microsoft SQL Server), y transfiere datos mediante bloques (chunks) a través de HTTPS con capacidad de reanudación inmediata ante cortes.

---

## 2. Diagrama de Arquitectura en Proxmox VE

```text
                                INTERNET / RED LOCAL
                                         │
                                         │ HTTPS / WebSockets
                                         ▼
                 ┌───────────────────────────────────────────────┐
                 │               SERVIDOR CENTRAL                │
                 │                  PROXMOX VE                   │
                 └───────────────────────┬───────────────────────┘
                                         │
                 ┌───────────────────────┴───────────────────────┐
                 │                                               │
                 ▼                                               ▼
     ┌───────────────────────┐                       ┌───────────────────────┐
     │   LXC 1: BACKEND      │                       │   LXC 2: STORAGE      │
     │   (Debian 12/13 CT100)│                       │   (Debian 12/13 CT101)│
     │                       │                       │                       │
     │ • FastAPI REST API    │   Punto de Montaje    │ • Almacenamiento ZFS  │
     │ • PostgreSQL 16 Nativo│ ────────────────────► │ • Aislamiento /client │
     │ • WebSockets Engine   │                       │ • Directorio Temporal │
     │ • Dashboard Web UI    │                       │ • Deduplicación / LVM │
     └───────────┬───────────┘                       └───────────────────────┘
                 │
                 │ HTTPS (Streaming Chunks 4MB + Hashing)
                 │
        ┌────────┴────────┐
        │                 │
        ▼                 ▼
 ┌──────────────┐  ┌──────────────┐
 │  Windows 11  │  │WinServer 2022│
 │ Backup Agent │  │ Backup Agent │
 └──────────────┘  └──────────────┘
```

---

## 3. Protocolo de Transferencia por Bloques (Chunks) y Reanudación

La transferencia de archivos grandes (ej. 50 GB) no utiliza envíos en una sola petición `POST` multipart monolítica, sino un protocolo secuenciado de subida por bloques:

```text
[Archivo database.bak (12 GB)]
         │
         ├── Chunk 000000 (4 MB) ──► SHA256 Chunk ──► Guardado en temp/{session}/00000000.chunk
         ├── Chunk 000001 (4 MB) ──► SHA256 Chunk ──► Guardado en temp/{session}/00000001.chunk
         ├── ...
         └── Chunk 003000 (4 MB) ──► SHA256 Chunk ──► Guardado en temp/{session}/00300000.chunk
                                                              │
                                                              ▼
                                                   [Ensamblado Secuencial]
                                                              │
                                                              ▼
                                                   [Validación SHA-256 Full]
                                                              │
                                                              ▼
                                          /storage/backups/clients/{client}/{job}/
```

### Ciclo de Vida de una Sesión de Subida

1. **Detección y Estabilidad (`is_file_stable`)**:
   - El agente comprueba que el archivo no posea un bloqueo exclusivo de escritura (`EACCES`/`EBUSY`) por parte de SQL Server y que su tamaño permanezca invariante durante la ventana configurada (`min_stable_time_seconds: 60s`).
2. **Inicio o Reanudación (`POST /api/upload/session`)**:
   - El agente envía el hash SHA-256 total precalculado, tamaño en bytes y nombre.
   - El backend busca si ya existe una sesión en progreso para ese hash. Si existe, responde con `received_chunks: [0, 1, 2, ...]`.
3. **Transmisión de Chunks Faltantes (`POST /api/upload/{session}/chunk`)**:
   - El agente transmite exclusivamente los bloques que el servidor aún no tiene.
   - El servidor almacena el bloque y valida su hash SHA-256 individual.
   - Cada bloque recibido emite un evento WebSocket `UPLOAD_PROGRESS` que actualiza el Dashboard en tiempo real.
4. **Ensamblado y Verificación de Integridad (`POST /api/upload/{session}/complete`)**:
   - El servidor concatena los bloques en streaming hacia el volumen final.
   - Calcula el hash SHA-256 en streaming del archivo ensamblado y lo compara contra el hash declarado.
   - Si coincide: Marca el archivo como `SUCCESS`, actualiza la cuota del cliente y ejecuta la política de retención.
   - Si difiere: Elimina el archivo corrupto y solicita retransmisión.

---

## 4. Aislamiento Estricto Multicliente

- Cada agente Windows posee credenciales únicas revocables (`X-Device-Id` y `X-Device-Token`).
- Los respaldos se estructuran físicamente en:
  `/storage/backups/clients/{CLIENT_CODE}/{JOB_CODE}/{TIMESTAMP}_{FILENAME}`
- Ningún cliente puede listar, sobrescribir ni acceder a las sesiones o archivos de otro cliente (validado a nivel de base de datos y sistema de archivos).
- La eliminación accidental de un archivo local en Windows **nunca** borra los backups remotos en el servidor.