ViewIT/docs/ARCHITECTURE.md

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.

• 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.