Twitch-VOD-Manager/tasks/v5.0.0-goal.md

Twitch VOD Manager — v5.0.0 Goal

Baseline: v4.6.155 (Stand 2026-05-11) Target: v5.0.0 Status: Draft / nicht freigegeben Sprache: Deutsch (Stack-Begriffe englisch)

---

1. Executive Summary

Nach 155 Patches im 4.6er-Zyklus ist das Produkt poliert, aber im Kern unverändert seit 4.0: monolithische main.ts (~3700 Zeilen), JSON-File-Persistenz, Vanilla-DOM-Renderer, kein Live-Recording, keine sub-only Unterstützung, keine Tests jenseits Playwright-Smoke.

v5.0.0 ist der Bruch: Aufnahme statt nur Download, SQLite statt JSON, modulare Domain-Architektur, Twitch-OAuth, optionales Web-Worker-Offloading für grosse Listen. Sieben Feature-Pillars, drei harte Breaking Changes, klarer Migrationspfad von 4.6.x.

Was 5.0.0 NICHT ist: kein React/Vue-Rewrite, kein Plattform-Hop (bleibt Electron + Win), kein neues Bezahlmodell. Es bleibt der gleiche Single-User-Desktop-Client — nur deutlich erwachsener.

---

2. Why Major Bump?

Ein Major-Sprung ist gerechtfertigt, wenn mindestens zwei Kriterien erfuellt sind:

Kriterium	5.0.0 trifft zu?	Belege
Breaking Change im Config-/Datenformat	Ja	JSON → SQLite Migration, Schema v4 → v5
Neues Kern-Feature (nicht Inkrement)	Ja	Live-Stream-Recording (sub-only via OAuth), Scheduled-Recording
Architektur-Bruch	Ja	main.ts Split in 6+ Domain-Module
Min-OS-/Runtime-Bump	Ja	Electron 28 → 32, Node 18 → 22, Drop Win < 10 1809
User-spuerbare UI-Verschiebung	Ja	Virtual-List, Mini-Player, Theme-Engine

---

3. Themes & Vision

Drei Leitthemen ueber allen Features:

3.1 Vom Downloader zum Recorder

v4 reagiert: VOD existiert auf Twitch → wir laden runter. v5 agiert proaktiv: Stream geht live → wir nehmen direkt mit. Damit fallen Sub-Only-VODs (oft 60 Tage Retention), 7-Tage-Standard-Retention und geloeschte VODs als Verlust-Szenarien weg.

3.2 Vom Tool zur Platform

Domain-Module mit klaren Schnittstellen statt einem 3700-Zeilen-Monolith. Optionaler Plugin-Hook fuer Post-Download-Actions (z. B. Auto-Upload-Skript, Custom-Rename, Notify-Discord). Spaeter wartbar, leichter testbar.

3.3 Vom Hobby zum stabilen Daily-Driver

SQLite + Crash-Recovery + Chunk-Hashing + echte Unit-Tests. Wer 500 VODs queued, soll nicht in JSON-Lock-Konflikte laufen oder beim Crash 4 Stunden Download verlieren.

---

4. Feature-Pillars

Pillar 1 — Live Stream Recording (P0)

Was: App kann laufende Streams in Echtzeit mitschneiden, nicht nur VODs post-hoc downloaden.

Warum: Sub-only Streams haben oft keine VOD-Retention oder Sub-only-VODs werden nach 60 Tagen geloescht. Recording ist der einzige Weg, sie dauerhaft zu sichern.

Scope:

• Streamlink-basierte Aufnahme aktiver Live-Streams (Quality-Selector wie bei VODs)
• Auto-Start: "wenn Streamer X live geht, Recording starten" (Polling-Intervall pro Streamer konfigurierbar, default 60s)
• Auto-Stop bei Stream-Ende + Final-Mux mit ffmpeg
• Resume bei Mid-Stream-Disconnect (neuer HLS-Segment-Pointer, append-Mode)
• Sub-only Streams: nutzt OAuth-Token aus Pillar 2

Acceptance:

• 4-Stunden-Test-Stream wird ohne Datenverlust aufgenommen
• Disconnect-Wiederherstellung in < 15s
• File-Output ist mux-fertig MP4 (kein .ts-Reste, kein orphan-Index)
• UI zeigt "LIVE REC" Badge + Recording-Dauer im Streamer-Eintrag

Pillar 2 — Twitch-OAuth (Device Code Flow) (P0)

Was: Native Anmeldung mit Twitch-Account, OAuth-Token wird verschluesselt in OS-Keychain (Win Credential Manager) gespeichert.

Warum: Sub-only Inhalte, hoehere Rate-Limits (Helix mit User-Token > App-Token in vielen Endpoints), private Follow-Liste fuer Auto-Discovery, korrekte Mature-Content-Gating-Behandlung.

Scope:

• Device Code Flow (kein Browser-Embed, kein localhost-Callback noetig — sauberer fuer Desktop)
• Multi-Account: bis zu 3 parallele Accounts (Haupt, Alt, Auto-Sub)
• Token-Refresh automatisch, Fail-Soft auf App-Token
• Settings-Tab "Accounts" mit Liste, Login/Logout, "Default fuer Recording"

Acceptance:

• Login dauert < 60s vom Klick bis Token in Keychain
• Sub-only Test-Channel laesst sich aufnehmen mit eingeloggtem Sub-Account
• Logout entfernt Token sauber aus Keychain (audit per Tool: kein orphan-Entry)

Pillar 3 — SQLite-Migration (P0, Breaking)

Was: Alle App-Daten (Queue, Stats, Archiv-Index, Streamer-Liste, Recording-History) wandern von JSON-Files nach app.db (better-sqlite3 oder besser-im-Bundle-Alternative).

Warum: JSON wird ab ~1000 VODs spuerbar lahm (Full-File-Rewrite bei jedem Save). SQLite gibt indexed lookups, atomic transactions, kein Lock-Konflikt bei parallelen Writes, einfache Migrationen.

Scope:

• Schema v5 mit Tabellen: queue, archive, streamers, recordings, stats_daily, clip_index, config_blob
• Migrator-Script: liest alle C:\ProgramData\Twitch_VOD_Manager\*.json und schreibt in app.db
• Backup vor Migration: .json → .json.v4-backup
• Read-Path bleibt API-kompatibel fuer Renderer (IPC-Surface unveraendert)
• WAL-Mode + busy-timeout 5000ms

Acceptance:

• Migrator laeuft idempotent (zweimal aufrufen = gleicher Endzustand, kein Daten-Duplikat)
• Failure-Rollback: bei Migrator-Crash bleibt App auf JSON, kein Daten-Verlust
• Query "alle VODs eines Streamers" < 50ms bei 10k Archiv-Eintraegen (gemessen)

Pillar 4 — Architektur-Refactor: main.ts Split (P1)

Was: main.ts (3700 LoC) wird in Domain-Module zerlegt.

Ziel-Struktur:

src/main/
  index.ts              Entry, app lifecycle, BrowserWindow
  domain/
    twitch-api.ts       Helix + GraphQL Calls, Rate-Limit-Handling
    downloader.ts       Streamlink/ffmpeg Orchestration (VOD + Live)
    recorder.ts         Live-Stream-Recording (NEU)
    queue.ts            Queue-State-Machine, persistence-call
    config.ts           Settings-Schema, defaults, validation
    auth.ts             OAuth, Token-Storage, Keychain (NEU)
    cache.ts            In-Memory-TTL-Caches
    updater.ts          electron-updater Wrapper
  infra/
    db.ts               SQLite-Wrapper, prepared statements
    logger.ts           Strukturiertes Logging (JSON-Lines)
    ipc.ts              Channel-Registry, type-safe Handler
  ipc-bridge.ts         exportiert nur die API-Surface fuer preload.ts

Constraint: Renderer-IPC-Surface bleibt rueckwaertskompatibel — kein Renderer-Rewrite noetig.

Acceptance:

• Kein Modul groesser als 800 LoC
• Zyklische Imports = 0 (madge --circular oder aequivalent)
• E2E-Tests gruen ohne Anpassung

Pillar 5 — UI Power-Features (P1)

Was: Renderer-seitige Spruenge, die User direkt sehen.

Scope:

• Virtualized List fuer Queue/Archive (react-window-aequivalent vanilla, oder @tanstack/virtual-core vanilla-Adapter) — 10k Eintraege ohne Lag
• Mini-Player Panel: HLS-Stream in App-eigenem <video> (hls.js), kollabierbar, fuer Recording-Live-Preview + VOD-Vorschau
• Theme-Engine: drei eingebaute Themes (Default, Dark High-Contrast, Light) + Custom-CSS-Slot mit Live-Reload
• Template-Preview live: Title-Template aendert sich, Beispiel-Output rendert in Echtzeit unter dem Input
• Drag-Reorder in Queue (HTML5-DnD, persistiert Position-Index in DB)
• Command-Palette (Ctrl+K): Schnellaktionen, Streamer-Suche, Settings-Jump

Acceptance:

• Scroll-Performance bei 5000 Eintraegen: 60fps (Chrome DevTools Performance-Trace)
• Theme-Switch ohne Reload
• Command-Palette < 100ms First-Result-Latency

Pillar 6 — Smart-Resume & Integrity (P1)

Was: Downloads/Recordings ueberleben Crash, Disconnect, Reboot.

Scope:

• Jeder HLS-Segment-Chunk bekommt sha1, geschrieben in DB-Tabelle chunk_index
• Bei Resume: vergleicht local-chunk-hash mit Manifest, ueberspringt valide Chunks, faengt am ersten Mismatch an
• Crash-Recovery beim Startup: scannt recordings-Tabelle nach state=running und bietet Resume-Dialog an
• Final-Integrity-Check: ffprobe-Aufruf auf fertige Datei, schreibt verified=1 in DB

Acceptance:

• App-Kill mid-download → Neustart → Resume genau ab Abbruch-Chunk (manueller Test)
• Korrupte Chunk-Datei wird erkannt und neu geladen (per Mutation-Test: zufaelliges Byte flippen)

Pillar 7 — Scheduled Recording & Auto-Discovery (P2)

Was: Automatisierungs-Layer ueber Pillar 1+2.

Scope:

• Pro Streamer: "Auto-Record on Live: ja/nein" + Quality-Preset
• Zeit-Plan: "nur zwischen 18-02 Uhr aufnehmen" (vermeidet Reruns/Marathons)
• Top-Clip-Crawler: pro Streamer alle X Tage die N besten Clips (Helix /clips) downloaden
• Follow-Sync: importiert eingeloggte Follow-Liste als Streamer-Eintraege (opt-in)

Acceptance:

• 3-Streamer-Auto-Record-Test ueber 24h ohne Eingriff, kein Doppelaufnahme bei Stream-Reconnect

---

5. Breaking Changes

#	Was bricht	Migration	User-Impact
BC-1	Config-Speicherort	Migrator on first 5.0 start, .v4-backup der JSONs bleibt liegen	Einmalig 5-30s Migrations-Dialog
BC-2	Min-Windows: Win10 1809 (Oktober 2018)	Installer-Check, blockiert Setup auf alten OS	Sehr wenige User betroffen
BC-3	Node-API-Version: Plugins die auf Node 18 N-API gebaut sind muessen rebuild (relevant fuer better-sqlite3, evtl. fsevents)	Pre-built Binaries im Bundle	Transparent fuer User
BC-4	Streamer-Eintrag-Format aendert sich (neue Felder: oauth_account_id, auto_record, record_quality)	Auto-Default bei Migration	Transparent
BC-5	Auto-Updater Channel: alte 4.x-Clients sehen 5.0 nicht im stable-Channel, sondern in next (opt-in)	User muss bewusst Channel wechseln; nach 4 Wochen Beta: 5.0 → stable	Bewusste User-Aktion

---

6. Tech-Stack Upgrades

Komponente	4.6	5.0	Grund
Electron	28.x	32.x (oder LTS aktuell)	Security-Patches, Chromium-Upgrade
Node	18	22	LTS, V8 perf
TypeScript	5.3	5.6+	satisfies / decorators stable
ESLint	10	aktueller flat-config	passt
Neu: better-sqlite3	—	latest	SQLite-Persistenz
Neu: hls.js	—	latest	Mini-Player
Neu: keytar (oder Electron safeStorage)	—	latest	OAuth-Token-Storage
Playwright	1.59	aktuell	E2E
Neu: vitest	—	latest	Unit-Tests

---

7. Quality & DevX

• Unit-Tests (Vitest): mind. 60% Coverage in src/main/domain/* zum 5.0.0-GA. Reine Logik-Tests, kein Electron-Boot.
• E2E (Playwright): bestehende Suite plus drei neue Szenarien (Login, Live-Record-Start, SQLite-Migration).
• CI: weiterhin lokal (Solo-Projekt), aber npm run check:all = build + lint + vitest + e2e in einem Skript.
• Logging: strukturiert JSONL in logs/app-YYYY-MM-DD.jsonl, 14-Tage-Retention, mit Level (debug/info/warn/error) und Trace-IDs pro Download/Recording.
• Crash-Reports: opt-in Sentry (oder einfacher: lokaler Crash-Log-Export + Copy-to-Clipboard-Button). Default: aus, kein Telemetrie-Surprise.

---

8. Release-Phasen

Phase	Version	Was rein	Wann (relativ)
Alpha-1	5.0.0-alpha.1	SQLite-Migrator + Architektur-Split	T+0
Alpha-2	5.0.0-alpha.2	OAuth + Live-Recording (Baseline)	T+2 Wo
Beta-1	5.0.0-beta.1	UI Power-Features, Smart-Resume	T+4 Wo
Beta-2	5.0.0-beta.2	Scheduled/Auto-Discovery, Bug-Fixes	T+6 Wo
RC	5.0.0-rc.1	nur noch Bugfixes, kein Feature-Add	T+8 Wo
GA	5.0.0	Public, next-Channel → stable	T+10 Wo

Konkret Daten setze ich nicht — die haengen davon ab, wie eng du das fahren willst.

---

9. Out-of-Scope (bewusst NICHT in 5.0.0)

• React/Vue/Svelte-Rewrite des Renderers (Risiko zu gross, Vanilla bleibt)
• macOS/Linux-Builds (Electron-Builder kann, aber kein Test-Setup → erst 5.1+)
• Cloud-Sync (Queue/Settings ueber Geraete) — eigener Major-Bump waert
• Chat-Recording / Chat-Renderer (TwitchDownloaderCLI Integration) — verlockend, aber Scope-Creep → 5.1
• Mobile-Companion-App
• Plugin-API fuer Dritte (Hooks koennen wir intern bauen, aber kein public-API-Versprechen in 5.0)
• AI-Highlight-Detection (lokales LLM) — Forschung, kein Produkt-Feature 2026

---

10. Definition of Done (5.0.0 GA)

Alle Punkte erfuellt:

1. Pillars 1-6 implementiert und in E2E-Tests abgedeckt (Pillar 7 darf teilweise sein, mind. Auto-Record-on-Live)
2. SQLite-Migrator getestet auf realer 4.6-Installation mit 5k+ Archive-Eintraegen, idempotent, mit Rollback-Path
3. OAuth-Token landet in Keychain, audit zeigt sauberen Logout
4. Vitest-Coverage src/main/domain >= 60%
5. Playwright-Suite gruen, inkl. drei neue Szenarien
6. Mini-Player + Theme-Engine + Virtual-List manuell verifiziert (Demo-Video)
7. Auto-Updater: bestehende 4.6-Installation kriegt 5.0 ueber next-Channel, Migration laeuft, App startet
8. README + CLAUDE.md aktualisiert (neue Architektur, neue Commands, neue Settings)
9. CHANGELOG-Eintrag mit allen Breaking Changes prominent oben
10. Frische Installation aus Twitch-VOD-Manager-Setup-5.0.0.exe auf clean Win11-VM: erstes Recording lauft binnen 5 Minuten User-Klicks

---

11. Naechste Schritte (wenn du dieses Goal annimmst)

1. Goal mit eigenem Realitaetscheck lesen — was streichen, was zuerst
2. Pillar 3 (SQLite) zuerst, weil es Voraussetzung fuer 1, 6, 7 ist
3. Branch feat/v5-foundation aufmachen, dort Architektur-Split + SQLite parallel
4. Nach Alpha-1 entscheiden, ob OAuth vor UI-Refactor oder umgekehrt
5. Eigenes tasks/v5.0.0-checklist.md aus Pillar-Acceptance-Criteria generieren, abhakbar

---

Autor: Claude (Opus 4.7, 1M context) — 2026-05-11 Review-Status: unreviewed, Erstentwurf