# dmunozv04/isponsorblocktv architecture

> Architecture diagram of the GitHub repository dmunozv04/isponsorblocktv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dmunozv04/isponsorblocktv
- Repository: https://github.com/dmunozv04/isponsorblocktv

## Overview

##### Project Type and Purpose
- iSponsorBlockTV is a networked, asynchronous Python service that:
- Discovers YouTube‑TV capable devices on the LAN (via SSDP/DIAL)
- Monitors playback on those devices (via pyytlounge)
- Queries the SponsorBlock API for skip segments (with caching)
- Commands the device to skip/mute segments
- Provides a CLI and Textual TUI for configuration

##### File Structure
Top‑level artifacts:
- Dockerfile & docker‑compose.yml – container build & deployment
- config.json.template – schema for persistent device + user config
- pyproject.toml / requirements.txt – language and dependency declarations
- src/main.py & src/main_tui.py – entry points (daemon vs config UI)
- src/iSponsorBlockTV/ – core library modules

Core modules inside src/iSponsorBlockTV:
- config_setup.py & setup_wizard.py (+ style.tcss) – configuration UI logic
- dial_client.py & ytlounge.py – network protocols for device control
- api_helpers.py – SponsorBlock API client
- conditional_ttl_cache.py – caching layer for API results
- main.py – orchestrator: discovery, monitoring, skip‑logic
- helpers.py, constants.py – utility functions & values

##### Extract Insights From the README
- Async Python + aiohttp + async-cache + SSDP + Textual
- Two modes:
– Daemon mode (main.py invoked via src/main.py)
– Config mode (main_tui.py invoked via src/main_tui.py)
- External systems: SponsorBlock API, YouTube‑TV devices (over network)
- Deployment via Docker

##### Components & Relationships
a. Main Components
1. Configuration Layer
– CLI (main.py)
– Textual TUI (main_tui.py & setup_wizard.py)
– config.json (persistent store)
2. Discovery & Registration
– SSDP module (ssdp library)
– Manual code entry from TUI
3. Device Communication
– DIAL Client (dial_client.py)
– pyytlounge Client (ytlounge.py)
4. Core Orchestrator (main.py)
– Event Loop (asyncio)
– Monitor tasks per device
– Skip logic coordinator
5. SponsorBlock API
– api_helpers.py (HTTP via aiohttp)
– conditional_ttl_cache.py (cache layer)
6. Action Executor
– Commands devices to skip/mute segments
7. Infrastructure & Deployment
– Docker / docker‑compose
– Logging / Error handling (helpers.py)

b. Data Flows & Interactions
1. Startup
– CLI/TUI reads config.json → User config entry (if first run)
– TUI writes config.json via config_setup
2. Discovery
– Orchestrator triggers SSDP → Discovers device IPs & capabilities
– or Accepts manual codes → Populates device registry
3. Monitoring Loop (per device)
– pyytlounge WebSocket connection → emits playback events
– Orchestrator sees “new video” or “seek” events
4. Skip Lookup
– On event, Orchestrator calls api_helpers → SponsorBlock API
– utilises conditional_ttl_cache to avoid repeated calls
5. Execute Skip
– Orchestrator sends skip commands via dial_client or ytlounge
6. Logging & Metrics
– helpers.log() captures success/failure, metrics

c. Architectural Patterns / Design Principles
- Asynchronous, event‑driven core using asyncio
- Layered design: UI → Orchestrator → Protocol clients → External APIs
- Single process, modular library + entry‑point scripts
- Configuration as code / persistent JSON + interactive setup

d. Key Technologies & Frameworks
- Python 3.x, asyncio, aiohttp
- async-cache
- ssdp (for discovery)
- pyytlounge (WebSocket control of YouTube‑TV devices)
- Textual (TUI configuration wizard)
- Docker / Docker‑Compose for containerization

##### Detail
– Capture each module if space allows (or group by layer)
– Show the caching layer sitting between API calls and orchestrator
– Highlight async event loop as the backbone

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        CLI["CLI Entry Point"]:::ui
        TUI["Textual TUI Entry Point"]:::ui
        SetupWizard["Configuration Wizard"]:::ui
        ConfigSetup["Config Setup Utilities"]:::ui
        TUIStyle["TUI Styling (.tcss)"]:::ui
        ConfigTemplate["config.json.template"]:::storage
    end

    %% Core Daemon
    subgraph "Core Daemon"
        Orchestrator["Orchestrator (async event loop)"]:::internal
        Helpers["Utility Functions & Logging"]:::internal
        Constants["Shared Constants"]:::internal
    end

    %% Protocol Clients
    subgraph "Protocol Clients"
        DialClient["DIAL Client"]:::internal
        YTLounge["YouTube-TV WebSocket Client"]:::internal
    end

    %% External Services
    subgraph "External Services"
        SponsorAPI["SponsorBlock API"]:::external
        YouTubeDevices["YouTube‑TV Devices"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        DockerfileNode["Dockerfile"]:::infra
        DockerCompose["docker-compose.yml"]:::infra
    end

    %% Data Flows & Interactions
    CLI -->|invokes| Orchestrator
    TUI -->|invokes| Orchestrator
    TUI -->|launches| SetupWizard
    SetupWizard -->|uses| ConfigSetup
    SetupWizard -->|writes| ConfigTemplate
    Orchestrator -->|logs via| Helpers
    Orchestrator -->|reads values| Constants

    Orchestrator -->|discovers/commands| DialClient
    Orchestrator -->|monitors events| YTLounge
    YTLounge -->|emits playback events| Orchestrator

    Orchestrator -->|fetch skip data| APIClient
    APIClient -->|uses cache| CacheLayer
    CacheLayer -->|provides cached data| APIClient
    APIClient -->|returns segments| Orchestrator

    Orchestrator -->|skip/mute commands| DialClient
    DialClient -->|controls| YouTubeDevices
    YTLounge -->|controls| YouTubeDevices

    %% Infrastructure usage
    Orchestrator -.->|containerized by| DockerfileNode
    CLI -.->|containerized by| DockerfileNode
    TUI -.->|deployed via| DockerCompose

    %% Click Events
    click CLI "https://github.com/dmunozv04/isponsorblocktv/blob/main/src/main.py"
    click TUI "https://github.com/dmunozv04/isponsorblocktv/blob/main/src/main_tui.py"
    click SetupWizard "https://github.com/dmunozv04/isponsorblocktv/blob/main/src/iSponsorBlockTV/setup_wizard.py"
    click ConfigSetup "https://github.com/dmunozv04/isponsorblocktv/blob/main/src/iSponsorBlockTV/config_setup.py"
    click TUIStyle "https://github.com/dmunozv04/isponsorblocktv/blob/main/src/iSponsorBlockTV/setup-wizard-style.tcss"
    click ConfigTemplate "https://github.com/dmunozv04/isponsorblocktv/blob/main/config.json.template"
    click DialClient "https://github.com/dmunozv04/isponsorblocktv/blob/main/src/iSponsorBlockTV/dial_client.py"
    click YTLounge "https://github.com/dmunozv04/isponsorblocktv/blob/main/src/iSponsorBlockTV/ytlounge.py"
    click Orchestrator "https://github.com/dmunozv04/isponsorblocktv/blob/main/src/iSponsorBlockTV/main.py"
    click APIClient "https://github.com/dmunozv04/isponsorblocktv/blob/main/src/iSponsorBlockTV/api_helpers.py"
    click CacheLayer "https://github.com/dmunozv04/isponsorblocktv/blob/main/src/iSponsorBlockTV/conditional_ttl_cache.py"
    click Helpers "https://github.com/dmunozv04/isponsorblocktv/blob/main/src/iSponsorBlockTV/helpers.py"
    click Constants "https://github.com/dmunozv04/isponsorblocktv/blob/main/src/iSponsorBlockTV/constants.py"
    click DockerfileNode "https://github.com/dmunozv04/isponsorblocktv/tree/main/Dockerfile"
    click DockerCompose "https://github.com/dmunozv04/isponsorblocktv/blob/main/docker-compose.yml"

    %% Styles
    classDef internal fill:#D0E6FF,stroke:#0366d6
    classDef external fill:#D0FFD6,stroke:#2ea44f
    classDef ui fill:#FFF5B1,stroke:#D29922
    classDef storage fill:#FFEBD1,stroke:#d15704
    classDef infra fill:#EEDDEE,stroke:#813BA5
```
