Skip to content

02-system-architecture.md

Latest commit

 

History

History
99 lines (74 loc) · 4.31 KB

02-system-architecture.md

File metadata and controls

99 lines (74 loc) · 4.31 KB

02-system-architecture.md

1. Filosofía de Diseño

Compossarr se construye bajo el principio de "Navegación Automatizada". El sistema debe ser capaz de gestionar bibliotecas masivas sin intervención humana constante, manteniendo la integridad de los datos y maximizando la compatibilidad del hardware.

La arquitectura se basa en tres pilares:

  1. Asincronismo Total: El procesamiento de video (pesado) está desacoplado de la interfaz de usuario.
  2. Consistencia de Rutas: Gestión inteligente de mapeos para coexistir con Sonarr/Radarr.
  3. Transparencia: El usuario siempre debe saber qué está haciendo la "brújula" y por qué.

2. Diagrama de Arquitectura

3. Capas del Sistema

3.1. Frontend (The Helm / El Timón)

  • Tecnología: React 18+ con TypeScript y Vite.
  • UI/UX: Tailwind CSS con una paleta de colores extraída directamente de la suite Arr para garantizar paridad estética.
  • Comunicación: * REST API: Para configuración y gestión de perfiles.
    • WebSockets (Socket.io): Para la telemetría en tiempo real (progreso de FFmpeg, velocidad de frames, bitrate actual y logs de la consola).

3.2. Backend API (The Navigator / El Navegante)

  • Tecnología: Python 3.11+ (FastAPI).
  • Funciones Core:
    • Integración Arr: Cliente asíncrono que consume las APIs de Sonarr/Radarr.
    • Orquestador de Tareas: Recibe señales (Webhooks/Polling) y decide qué archivos requieren intervención.
    • Gestor de Hardware: Detecta dinámicamente /dev/dri, nvidia-smi y capacidades de la CPU para exponerlas al motor de transcodificación.

3.3. Worker Pool (The Crew / La Tripulación)

  • Gestor de Colas: Redis + BullMQ (o Celery).
  • Procesamiento: * FFprobe Wrapper: Analiza cada stream y lo traduce a un modelo de datos estructurado.
    • FFmpeg Engine: Construye comandos dinámicos basados en el perfil de optimización y el hardware detectado.
  • Aislamiento: Los procesos de transcodificación corren en "sandboxes" para que un error en un archivo no detenga toda la cola de trabajo.

3.4. Capa de Datos (The Logbook / El Diario)

  • Base de Datos: SQLite 3.
  • Persistencia: Guardada en el volumen /config.
  • Estructura: Almacena el estado de los archivos (Optimizado, Pendiente, Ignorado), los perfiles de usuario y el historial de ahorro de espacio.

4. Estrategia de Aceleración por Hardware (HWA)

Compossarr implementa una jerarquía de codecs para garantizar la máxima velocidad:

Prioridad Hardware Codec Encoder (H.265) Flags de FFmpeg
1 (NVIDIA) GPU NVENC hevc_nvenc -hwaccel cuda -hwaccel_output_format cuda
2 (Intel) iGPU QuickSync hevc_qsv -hwaccel qsv -qsv_device /dev/dri/renderD128
3 (AMD/Gen) VAAPI hevc_vaapi -hwaccel vaapi -vaapi_device /dev/dri/renderD128
4 (Software) CPU (Multi-core) libx265 -preset fast -crf 22

5. Gestión de Rutas y Volúmenes (Docker)

Para que la brújula no se pierda, Compossarr necesita ver el mismo sistema de archivos que los otros Arrs. Se recomienda el uso de Hardlinks y una estructura de datos unificada.

Configuración recomendada en Docker Compose:

services:
  compossarr:
    image: compossarr:latest
    container_name: compossarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Madrid
    volumes:
      - /opt/compossarr/config:/config
      - /mnt/media:/data  # Debe coincidir con la raíz de medios de los otros Arrs
    devices:
      - /dev/dri:/dev/dri # Requerido para Intel/VAAPI
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

6. Flujo de Comunicación (Sequence)

  1. Sonarr/Radarr envía un Webhook a Compossarr tras importar un archivo.
  2. Compossarr API valida el archivo y lo registra en la DB.
  3. Worker ejecuta ffprobe y detecta si los nombres de las pistas están "sucios" o el codec es ineficiente.
  4. Redis Si el archivo no cumple el "Norte", se añade a la Cola de Redis.
  5. FFmpeg El Worker de FFmpeg procesa el archivo.
  6. Sonarr/Radarr Al finalizar, se reemplaza el archivo original (operación atómica) y se notifica vía API a Sonarr/Radarr para un "Refresh".