# macielg1/vodrecovery architecture

> Architecture diagram of the GitHub repository macielg1/vodrecovery, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/macielg1/vodrecovery
- Repository: https://github.com/macielg1/vodrecovery

## Overview

##### Project Type and Purpose
- This is an open-source, command-line Python application (“Vod Recovery”) designed to fetch and download Twitch live streams, VODs, highlights, and clips by orchestrating HTTP scrapers, download engines (ffmpeg/yt-dlp), and optional trimming or live-watch features.

##### File Structure Analysis
- Top-level scripts:
- install_dependencies.py – bootstraps Python packages & ffmpeg
- vod_recovery.py – main CLI entrypoint
- Configuration:
- config/settings.json, config/help.json – customizable options, help text
- Libraries/helpers:
- lib/domains.txt, lib/user_agents.txt – lists for HTTP requests
- lib/install_ffmpeg.py – helper to install or validate ffmpeg
- lib/requirements.txt – Python dependencies
- Shortcuts: .bat/.sh wrappers for quick CLI invocation

##### README Insights
- Core features outline the functional modules: URL parsing (Twitch/TwitchTracker/SullyGnome/Streamscharts), download backend (ffmpeg or yt-dlp), M3U8 unmute/trimming, live recording/watch.

##### Detailed Yet Focused
- At least these components: User CLI, Config Manager, URL Scraper, Download Engine, M3U8 Processor, External Services, Storage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User CLI"]:::external
    Shortcuts["Shortcuts"]:::external

    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Parser & Command Dispatcher"]:::internal
        Bootstrap["Dependency Installer"]:::internal
    end

    %% Configuration
    Config["Configuration Manager"]:::internal

    %% Core Logic
    subgraph "Core Logic"
        subgraph "URL Resolver & Scraper"
            ResolverCore["URL Resolver"]:::internal
            Domains["domains.txt"]:::internal
            UserAgents["user_agents.txt"]:::internal
        end
        Download["Download Engine"]:::internal
        Processor["M3U8 Processor"]:::internal
    end

    %% Download Backends
    subgraph "Download Backends"
        YTDLP["yt-dlp"]:::external
        FFMPEG["ffmpeg"]:::external
    end

    %% External Services
    subgraph "External Services"
        Twitch["Twitch API/Web"]:::external
        TwitchTracker["TwitchTracker"]:::external
        Sully["SullyGnome"]:::external
        Streamscharts["Streamscharts"]:::external
    end

    %% Storage & I/O
    Storage["File Storage"]:::io

    %% Connections
    User -->|"invoke CLI"| CLI
    Shortcuts -->|"shortcut to CLI"| CLI
    CLI -->|"install dependencies"| Bootstrap
    CLI -->|"load config (JSON)"| Config
    CLI -->|"dispatch command"| ResolverCore

    Config -->|"settings, help JSON"| ResolverCore
    Config -->|"settings JSON"| Download

    ResolverCore -->|"HTTP GET"| Twitch
    ResolverCore -->|"HTTP GET"| TwitchTracker
    ResolverCore -->|"HTTP GET"| Sully
    ResolverCore -->|"HTTP GET"| Streamscharts
    ResolverCore -->|"metadata"| Download

    Download -->|"spawn ffmpeg process"| FFMPEG
    Download -->|"spawn yt-dlp process"| YTDLP
    Download -->|"media segments"| Processor

    Processor -->|"write MP4/TS"| Storage

    %% Click Events
    click Shortcuts "https://github.com/macielg1/vodrecovery/tree/main/shortcuts"
    click CLI "https://github.com/macielg1/vodrecovery/blob/main/vod_recovery.py"
    click Bootstrap "https://github.com/macielg1/vodrecovery/blob/main/install_dependencies.py"
    click Config "https://github.com/macielg1/vodrecovery/tree/main/config"
    click Domains "https://github.com/macielg1/vodrecovery/blob/main/lib/domains.txt"
    click UserAgents "https://github.com/macielg1/vodrecovery/blob/main/lib/user_agents.txt"
    click FFMPEG "https://github.com/macielg1/vodrecovery/blob/main/lib/install_ffmpeg.py"
    click YTDLP "https://github.com/macielg1/vodrecovery/blob/main/lib/requirements.txt"
    click README "https://github.com/macielg1/vodrecovery/blob/main/README.md"

    %% Styles
    classDef internal fill:#D0E6FF,stroke:#0366D6,stroke-width:1px
    classDef external fill:#DFFFE0,stroke:#2E8B57,stroke-width:1px
    classDef io fill:#FFE4B5,stroke:#FF8C00,stroke-width:1px
```
