## ViewIT Architekturüberblick

Dieses Dokument fasst die wichtigsten Kernmodule des Addons und ihre Aufgaben zusammen.
Es ergänzt die Detaildokumente `DEFAULT_ROUTER.md` und `PLUGIN_SYSTEM.md`.

### Ebenen und Verantwortlichkeiten

- **Router (`addon/default.py`)**
  - Einstiegspunkt aus Kodi (Parsing von `sys.argv`).
  - Lädt und verwaltet alle Plugins (Discovery, Instanziierung, Fehlerisolation).
  - Baut die Kodi-Menüs (Titel-, Staffel-, Episodenlisten, Spezialmenüs).
  - Mapped UI‑Aktionen (`search`, `seasons`, `episodes`, `play_*`) auf Plugin-Methoden.
  - Startet Playback und hält Kodi-Playstate konsistent (Resume/Watched).

- **Plugin-Vertrag (`addon/plugin_interface.py`)**
  - Definiert `BasisPlugin` als zentrale abstrakte Basisklasse.
  - Kern-API:
    - `search_titles(query, progress_callback?)`
    - `seasons_for(title)`
    - `episodes_for(title, season)`
  - Optionale Fähigkeiten:
    - Stream-Auflösung (`stream_link_for`, `resolve_stream_link`)
    - Metadaten (`metadata_for`, `genres`, `titles_for_genre`, `popular_series`, `capabilities`).
  - Dient als Referenz für alle konkreten Provider in `addon/plugins/`.

- **Plugin-Hilfen (`addon/plugin_helpers.py`)**
  - Zugriff auf Addon-Settings als String/Bool/Int (robust, auch außerhalb von Kodi).
  - Optionale URL‑Benachrichtigungen im UI (`notify_url`).
  - Strukturierte Logging-Helfer (`log_url`, `log_error`, `dump_response_html`) mit Rotationslogik.
  - Normalisierung von speziellen Stream-URLs (`normalize_resolved_stream_url`).
  - Fokus: Wiederverwendbare Infrastruktur für alle Plugins, ohne deren Kernlogik zu vermischen.

- **HTTP Session Pool (`addon/http_session_pool.py`)**
  - Verwaltet wiederverwendete `requests.Session`‑Instanzen pro Schlüssel.
  - Ziel: TCP‑Verbindungen und Cookies über mehrere Requests hinweg wiederverwenden.
  - Bietet `get_requests_session(key, headers?)` und `close_all_sessions()`.
  - Wird von Plugins oder Hilfsmodulen genutzt, die viele HTTP‑Aufrufe pro Sitzung machen.

- **TMDB-Integration (`addon/tmdb.py`)**
  - Kapselt alle Zugriffe auf die TMDB‑API (TV‑Shows, Staffeln, Episoden, Filme).
  - Enthält Datenklassen für Cast‑Mitglieder, Shows, Staffeln und Filme.
  - Nutzt ein threadlokales `requests.Session`‑Pooling für parallele Metadatenabfragen.
  - Wird vom Router genutzt, um Plugin-Metadaten optional mit TMDB‑Daten anzureichern.

- **Metadaten-Helfer (`addon/metadata_utils.py`)**
  - Berechnet plugin-spezifische Setting‑IDs für Metadatenquellen.
  - Entscheidet pro Plugin und User‑Setting, ob Quelle, TMDB oder Mix bevorzugt wird.
  - Sammelt Metadaten aus Plugins (`collect_plugin_metadata`) und merged sie mit TMDB (`merge_metadata`).
  - Liefert Signale, wann ein TMDB‑Fallback nötig ist (`needs_tmdb`).

- **ResolveURL Backend (`addon/resolveurl_backend.py`)**
  - Optionales Backend, das `script.module.resolveurl` nutzt, wenn installiert.
  - Versucht Hoster‑Links in abspielbare Media‑URLs aufzulösen.
  - Speichert den letzten Fehlerzustand (`get_last_error`) für Logging oder User‑Feedback.
  - Ist vollständig optional und bricht das Addon nicht, wenn ResolveURL fehlt.

- **Regex-Muster (`addon/regex_patterns.py`)**
  - Zentrale Sammlung wiederverwendeter Regulärer Ausdrücke (Staffel/Episoden‑Tags, Ziffern etc.).
  - Ziel: Konsistenz und Vermeidung von fehleranfälligem Copy/Paste in Plugins.

- **yt-dlp Helper (`addon/ytdlp_helper.py`)**
  - Kapselt Zugriffe auf `yt-dlp` zum Auflösen von Stream-URLs.
  - Wird als optionales Backend für Hoster genutzt, die weder ResolveURL noch direkte Links liefern.

- **Genre-Helfer (`addon/genre_utils.py`)**
  - Hilfsfunktionen für Genre-Normalisierung und -Mapping (plugin-übergreifend wiederverwendbar).

- **Such-Helfer (`addon/search_utils.py`)**
  - Gemeinsame Logik für titelbasierte Volltextsuche (Wortmatch, Normalisierung).
  - Wird vom Router genutzt, um Plugin-Suchtreffer konsistent zu filtern.

- **Kern-Module (`addon/core/`)**
  - `trakt.py` – Trakt.tv-Integration (OAuth, Scrobbling, Watchlist, Upcoming, History).
  - `metadata.py` – Metadaten-Aggregation aus Plugins und TMDB.
  - `gui.py` – Dialog-Helfer und UI-Utilities (z.B. Changelog-Dialog).
  - `playstate.py` – Playstate-Hilfsfunktionen (Schlüssel­berechnung, Zustandsabfrage). Eigenes Resume/Watched ist deaktiviert; Kodi verwaltet das selbst.
  - `plugin_manager.py` – Plugin-Discovery und -Instanziierung.
  - `router.py` – Routing-Helfer und Aktions-Dispatch.
  - `updater.py` – Versionsprüfung und Addon-Update-Flow.

- **Plugins (`addon/plugins/*.py`)**
  - Konkrete Integrationen zu einzelnen Providern (z.B. Serien-/Filmportale).
  - Implementieren `BasisPlugin` und optional zusätzliche Capabilities.
  - Verwenden die oben beschriebenen Hilfs‑ und Infrastrukturmodule.