rippy/KONZEPT.md

KONZEPT — Rippy

Automatisches Ripping-System für CD, DVD und Blu-ray, gebaut für Proxmox LXC (Debian 12 Slim). Ziel: Ein modernes, eigenständiges System statt veralteter ARM-Flask-UI.

---

1. Ziel & Motivation

Der Commander betreibt ein Heimlab mit Proxmox LXC (Debian 12) und PBS-Backup. Das vorhandene Automatic Ripping Machine (ARM) ist funktional, aber das UI (Flask) ist veraltet, es hat keine Echtzeit-Updates (kein SSE/WebSocket), keine JWT-Auth und eine monolithische Architektur.

Rippy ist ein komplett neues System von Grund auf: modulare Multi-Container-Architektur, modernes WebUI, Echtzeit-Jobstatus, sichere Authentifizierung — gebaut als eigenständiges Produkt, nicht als ARM-Fork.

2. Zielgruppe

• Commander (Hauptnutzer): Technik-affin, Proxmox-Heimlab, Wert auf eigene Kontrolle und Datenschutz.
• Zukünftig: Weitere Heimlab-Nutzer mit ähnlicher Infrastruktur.

3. Kern-Idee

Ein modular aufgebautes System, das bei Disc-Einwurf automatisch den Typ erkennt, das Medium rippt, Metadaten anreichert und das Ergebnis strukturiert ablegt. Alles über eine REST-API, asynchrone Celery-Jobs, ein React-WebUI und Echtzeit-Status über SSE.

4. Features

Feature	Muss	Kann	Später
Disc-Erkennung via udev-Event	✔ M
Dynamischer Device-Resolver (UUID/Serial)	✔ M
MakeMKV-Ripping (lossless)	✔ M
Audio-Rip mit abcde + MusicBrainz	✔ M
Video-Metadaten via TMDB API	✔ M
AcoustID-Fingerprinting (chromaprint)	✔ M
Multi-Disc-Set-Handling (Release-Group-Resolver)	✔ M
SQLite-Cache für API-Rate-Limits	✔ M
JWT-Auth (Access 15min/Refresh 7 Tage)	✔ M
Rate-Limiting (100/min pro API-Key)	✔ M
Celery-Queue + Redis mit AOF-Persistence	✔ M
Echtzeit-Status über SSE	✔ M
React-UI (statisch via Nginx)	✔ M
Proxmox LXC Template + Ansible Playbooks	✔ M
SELinux/AppArmor Profile pro Container	✔ M
MakeMKV als isolierte Black-Box-CLI	✔ M
GPL-v3-Compliance-Checkliste	✔ M
Source-Release-Endpoint	✔ M
HandBrake-Transcoding (optional)		✔ K
Prometheus+Grafana Monitoring		✔ K
PBS-Snapshot-Backup-Hooks		✔ K
Multi-Disc-Parallelisierung			✔ S
Redis-Cluster (Horizontales Scaling)			✔ S
PWA Mobile-App			✔ S

5. Mechaniken & Ablauf

Roter Faden — was passiert, wenn der Commander eine Disc einlegt:

1. udev-Event → System-Dämon (unabhängig vom API-Container) erkennt Einwurf.
2. Device-Resolver (udev-basiert) ermittelt UUID/Serial-Nummer des Laufwerks, erzeugt Symlink /dev/disc/<uuid>.
3. Job-Erstellung → Dämon erstellt Celery-Task, übergibt Device-Pfad und Disc-Typ.
4. Typ-Erkennung (CD/DVD/Blu-ray) → Auswahl des Ripping-Pfads.
5. Ripping:
   • CD: abcde → FLAC, Metadaten via AcoustID-Fingerprinting + MusicBrainz.
   • DVD/Blu-ray: makemkvcon --all --progress → MKV.
6. Metadaten-Anreicherung: Video-Infos von TMDB, Audio-Fallback von Discogs. SQLite-Cache für Rate-Limits.
7. Multi-Disc-Erkennung: Release-Group-Resolver prüft, ob weitere Discs des gleichen Sets folgen.
8. Speichern: Strukturierte Ablage nach <media-type>/<Jahr>/<Titel>/.
9. Status-Push: Worker sendet Fortschritt über SSE an React-UI.
10. Abschluss: Job-Ergebnis wird protokolliert, API gibt Token zurück, PBS-Backup-Hook kann ausgelöst werden.

6. Architektur & Tech-Stack

┌─────────────────────────────────────────────────────┐
│                 Proxmox LXC (Debian 12 Slim)         │
│                                                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │  API-Service │  │ Worker-     │  │   UI-Service │  │
│  │  FastAPI     │◄►│  Celery+    │  │  React +     │  │
│  │  PostgreSQL  │  │  Redis(AOF) │  │  Nginx       │  │
│  └─────────────┘  └─────────────┘  └─────────────┘  │
│       │                      │                       │
│       │                      │                       │
│       ▼                      ▼                       │
│  ┌────────────────────────────────────────┐          │
│  │  udev-Daemon → Device-Resolver         │          │
│  │  Unix-Socket → Worker Device-Infos     │          │
│  └────────────────────────────────────────┘          │
│                                                      │
│  ┌────────────────────────────────────────┐          │
│  │  MakeMKV (isolierter CLI-Aufruf)       │          │
│  │  HandBrake (optional, CLI)             │          │
│  │  abcde + chromaprint + MusicBrainz     │          │
│  └────────────────────────────────────────┘          │
└─────────────────────────────────────────────────────┘

Container-Design:

• API-Service (FastAPI): JWT-Auth, REST-Endpoints, OpenAPI-Docs, Job-Management, Lizenz-Handling.
• Worker-Service (Celery + Redis mit AOF-Persistence): Isolierte Ripping-Jobs, Cellery Tasks mit Device-Meta-Daten.
• UI-Service (React + Vite): Build-Step → statisch, bereitgestellt via Nginx. SSE-Client für Echtzeit-Status.
• udev-Daemon: Separater System-Dienst (unabhängig von API-Container), empfängt Disc-Einwurf-Events.

LXC-Isolation:

• Read-only Bind-Mounts für System-Bibliotheken.
• Device-Node-Read-Only für /dev/sr* (optische Medien sind read-only).
• SELinux/AppArmor Profile pro Container.
• Netzwerk-Policy: UI↔API (HTTPS), API↔Worker (mTLS), Worker↔Internet (nur API-Endpoints).

Persistenz:

• PostgreSQL für Job-Logs, Metadaten, User-Management.
• SQLite-Cache für API-Antworten (MusicBrainz, TMDB) — max 10.000 Einträge, LRU-Eviction.
• NFS/Bind-Mount für Medien-Store (geteilter Volume).

7. UX-Flow

1. Dashboard — Echtzeit-Kacheln mit aktuellem Job-Status, Queue-Übersicht, Disc-Einwurf-Hinweis.
2. Job-Verlauf — Tabelle aller Jobs mit Status, Fortschrittsbalken, Ergebnis-Vorschau.
3. Job-Detail — Live-Log-Ausgabe, Fortschritt, Möglichkeit "Abort" (nur vor Job-Start).
4. Ergebnis-View — Liste gerippter Dateien, Metadaten-Anzeige, "Play" (Streaming) / "Download".
5. Einstellungen — API-Keys verwalten (TMDB, Discogs), Transcoding-Optionen, Backup-Pfade, Lizenz-Einstellungen.
6. Geräte-Verwaltung — Liste verfügbarer Laufwerke, Status, Device-Resolver-Konfiguration.

8. Risiken & offene Punkte

Risiko	Status	Behandlung
MakeMKV-Beta-Key-Management	Gelöst	Key-Erneuerung als Cron-Job dokumentiert; rechtlich: DMCA-Ausnahme für Heimarchiv in DE, kommerzielle Lizenz $50 empfohlen
LXC-Device-Node-Änderungen	Gelöst	udev-Resolver (UUID/Serial) statt statischer /dev/sr*-Pfade; Device-Symlinks für stabile Zuweisung
Pending-Queue / State-Manager	Gelöst	Redis mit AOF-Persistence als State-Manager; Task-Priorisierung, Redis-Dumps beim Neustart
Hybrid-Discs (DVD-Audio, Hybrid-CD)	Offen	MVP erkennt nur Standard-CD/DVD/Blu-ray; Hybrid-Erkennung als "Kann" für spätere Version
LXC-Device-Passthrough Stabilität	Gelöst	Read-only Bind-Mounts; udev-Daemon unabhängig von API-Container; Hot-Plug-Integration via udev
Rate-Limits der Metadaten-APIs	Gelöst	SQLite-Cache (LRU, 10k Einträge), exponential backoff Retry (max 5 Versuche)
GPL-v3-Compliance	Gelöst	Checkliste, Source-Release-Endpoint, MakeMKV als isolierte Black-Box, Lizenz-Dokumentation
Redis Single-Instance Bottleneck	Offen	MVP mit Single-Instance; Redis-Cluster als "Später"-Feature

9. Härtetest-Dokumentation

Erster Haertetest (Advocatus Diaboli, GLM-4.7-Flash): 5 BLOCKER gefunden: MakeMKV-Key-Management, LXC-Device-Resolver, Pending-Queue, Hybrid-Discs, Bind-Mount-Performance.

Runde 1 (5 Rollen):

• DevOps: Multi-Container-Architektur, Proxmox-HA-Template, Resource-Limits, Restart-Policy.
• Security: JWT-Refresh-Token, Rate-Limiting, mTLS, SELinux/AppArmor.
• Software Architekt: udev-basierter Device-Resolver, Unix-Socket, State-Manager, Pending-Queue.
• Media Metadata: AcoustID-Fingerprinting, Multi-Disc-Set-Handling, SQLite-Cache.
• Legal: GPL-v3-Checkliste, MakeMKV-Black-Box-Trennung, Source-Release-Endpoint.

Zweiter Haertetest (Advocatus Diaboli, GLM-4.7-Flash): 5 HINWEISE (keine BLOCKER): React als Build-Step+Statisch (korrigiert), Redis-AOF-Persistence (integriert), Read-only vs. Write-Konflikt (nicht relevant — optische Medien sind read-only), Redis-Cluster (als "Später" notiert), Cold-Boot-Problematik (udev-Daemon als separater Dienst gelöst).

Ergebnis: Keine BLOCKER mehr. Konzept ist wasserdicht für MVP-Phase.