Skip to content

04-api-and-db-schema.md

Latest commit

 

History

History
94 lines (78 loc) · 4.33 KB

04-api-and-db-schema.md

File metadata and controls

94 lines (78 loc) · 4.33 KB

04-api-and-db-schema.md

1. Filosofía de Datos

Compossarr utiliza SQLite para la persistencia de datos. El objetivo principal de la base de datos es actuar como un "cerebro" que evite el re-procesamiento innecesario de archivos, mantenga un registro histórico de las optimizaciones y gestione la normalización de metadatos sin depender de escaneos constantes al disco duro.

2. Esquema de la Base de Datos (Relacional)

2.1. Tabla: instances

Almacena la configuración de conexión con Sonarr y Radarr y el estado de la auto-inyección.

Campo Tipo Descripción
id Integer (PK) Identificador único de la instancia.
type String Tipo de servicio (sonarr o radarr).
hostname String URL o IP del servicio.
api_key String Clave de API para comunicación.
webhook_id Integer ID del webhook inyectado automáticamente por Compossarr.
is_active Boolean Estado de la conexión.

2.2. Tabla: media_files

Contiene la información de cada archivo multimedia detectado en las librerías sincronizadas.

Campo Tipo Descripción
id Integer (PK) Identificador interno.
instance_id Integer (FK) Relación con la tabla instances.
arr_id Integer ID único asignado por Sonarr/Radarr.
path String (Index) Ruta absoluta del archivo en el sistema.
status Enum PENDING, ANALYZING, OPTIMIZING, COMPLETED, FAILED.
size_original BigInt Tamaño del archivo antes de procesar.
size_current BigInt Tamaño del archivo tras la optimización.
last_scan DateTime Fecha del último análisis técnico (FFprobe).

2.3. Tabla: tracks

Detalle técnico de cada flujo de datos dentro de un archivo para la normalización de nombres.

Campo Tipo Descripción
id Integer (PK) ID único de la pista.
file_id Integer (FK) Relación con media_files.
stream_index Integer Índice del stream en el contenedor (ej: 0:1).
type Enum video, audio, subtitle.
language String Código de idioma (ej: spa, eng).
title_raw String Título original detectado (ej: [UploaderX] Esp 5.1).
title_clean String Título normalizado según perfil (ej: Español 5.1 AC3).

3. Definición de la API (Endpoints)

3.1. Gestión de Conexiones

  • POST /api/instances/connect: Recibe credenciales, realiza el apretón de manos (handshake) e inyecta el webhook de Compossarr en el servicio Arr de forma automática.
  • GET /api/instances: Devuelve el listado de servicios conectados y su estado de sincronización.

3.2. Operaciones de Biblioteca

  • GET /api/media: Lista paginada de todos los archivos con filtros por estado, instancia y ahorro de espacio.
  • POST /api/media/{id}/analyze: Fuerza un re-análisis manual de un archivo específico mediante FFprobe.
  • POST /api/media/{id}/optimize: Añade manualmente un archivo a la cola de procesamiento.

3.3. Webhooks (Recepción)

  • POST /api/webhooks/arr: Endpoint destinado a recibir los avisos automáticos de Sonarr/Radarr sobre nuevas descargas, cambios de nombre o eliminaciones de archivos.

3.4. Monitorización de Tareas (Queue)

  • GET /api/queue: Lista de tareas activas en Redis.
  • DELETE /api/queue/{id}: Cancela una tarea de procesamiento en curso.

4. Comunicación en Tiempo Real (WebSockets)

Para replicar la fluidez visual de las herramientas Arr, se utiliza Socket.io para emitir los siguientes eventos al Frontend:

  • global_stats: Actualización de los contadores de espacio ahorrado y archivos pendientes.
  • task_progress: Envío periódico de datos de FFmpeg (porcentaje, FPS, tiempo restante).
  • console_logs: Streaming de las líneas de log del proceso actual para depuración visual del usuario.

5. Esquema de Perfiles de Optimización (JSON)

Los perfiles definen el "Norte" de la brújula. Se almacenan como objetos JSON configurables:

{
  "name": "Estandar Home Cinema",
  "video": {
    "codec": "hevc",
    "action": "transcode_if_not_match"
  },
  "audio": {
    "keep_languages": ["spa", "eng"],
    "naming_format": "{language} {channels} {codec}"
  },
  "subtitles": {
    "convert_to_srt": true,
    "remove_image_subs": true
  }
}