# book000/youtube-live-recorder architecture

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

- Interactive diagram: https://gitdiagram.com/book000/youtube-live-recorder
- Repository: https://github.com/book000/youtube-live-recorder

## Overview

##### Project type & purpose (from README + tree)
This is a **Dockerized automation tool** (“youtube-live-recorder”) that **monitors a YouTube Channel or Playlist and records/downloads live videos** into a target directory. It’s not a full-stack web app; it’s a **headless worker/CLI-style service** intended to run via **Docker Compose** with configuration supplied by an env file (`recorder.env`).

Key runtime behaviors implied by the repo:
- **Polling/monitoring**: detect a new live stream / newly available video for a given `CHANNEL` or `PLAYLIST`, optionally filtered by `TITLE_FILTER`.
- **Recording/downloading**: once detected, download/record the stream (very likely via external CLI tools packaged in the container image).
- **Persistence**: save outputs to disk under a directory named by `TARGET`.

##### File structure → architectural hints
Top-level:
- `docker-compose.yml`: primary runtime entrypoint for end users; defines one or more services, volumes, env injection.
- `watch-new-movie/`: a Node.js/TypeScript subproject that is almost certainly the **watcher** component:
- `watch-new-movie/src/main.ts`: main watcher logic entrypoint.
- `watch-new-movie/package.json`, `tsconfig.json`, lint configs: confirms TS CLI/service.
- `watch-new-movie/Dockerfile` + `watch-new-movie/entrypoint.sh`: strongly suggests the watcher can be built/run as its own container OR embedded into the root image.

##### docker-compose stack
- **Service: youtube-live-recorder** (name from compose; if unknown, label generically)
- Built from `Dockerfile` (root)
- Started via `entrypoint.sh`
- Receives env from `recorder.env` (document variables: `TARGET`, `CHANNEL`/`PLAYLIST`, `TITLE_FILTER`)
- Mounts volume/bind mount for output directory

##### Internal logical runtime processes (even if same container)
- **Watcher process** (from `watch-new-movie/src/main.ts`)
- Responsibility: poll channel/playlist, apply title filter, emit “video id / live url / job trigger”
- **Recorder/Downloader process** (implied by “Record and download YouTube live videos” + presence of shell entrypoint scripts)
- Responsibility: invoke downloader/recorder toolchain; manage retries; write files
- **Filesystem writer** (can be a subcomponent): ensures directory naming based on `TARGET`, organizes outputs

##### Dependencies packaged in the image
- **Download/record tool** (e.g., yt-dlp/ffmpeg-like functionality)
- **Shell orchestration** (`entrypoint.sh`)

- `entrypoint.sh` → Watcher: “start watcher loop”
- Watcher → Recorder: “trigger recording for video/stream”
- Recorder → YouTube CDN: “media download”
- Recorder → Output Volume: “write .mp4/.ts + metadata”
- Watcher → YouTube metadata endpoints: “list channel/playlist items; detect live”

- **Config Loader**
- Reads env: `TARGET`, `CHANNEL`, `PLAYLIST`, `TITLE_FILTER`
- Validates: “Either CHANNEL or PLAYLIST required”
- **YouTube Discovery Client**
- Fetches latest videos / live status for channel/playlist
- Produces a normalized list of candidate videos
- **Filter Engine**
- Applies `TITLE_FILTER`
- **State/De-duplication**
- Avoid re-recording the same video (store seen IDs)
- Where state lives: filesystem (under `TARGET`), in-memory, or a small state file (represent as “Local State Store” even if just a file)
- **Job Trigger / Orchestrator**
- Calls the recorder/downloader (shell exec)
- Handles concurrency (single flight vs parallel)
- **Logging/Telemetry**
- Logs to stdout (container logs)

Interactions:
- Config Loader → Discovery Client: supplies IDs and options
- Discovery Client → Filter Engine → State Check → Trigger Recorder
- Trigger Recorder → “Recorder CLI toolchain”
- Recorder toolchain → Output FS

##### Architectural patterns / principles to highlight (specific to this project)
- **Worker pattern / daemon loop**: a long-running container that polls and reacts.
- **Separation of concerns**:
- “Discovery/Decision” (watch-new-movie Node/TS)
- “Execution” (record/download toolchain via shell)
- **Immutable runtime packaging**: Docker image contains everything required; Compose injects config and storage.
- **External system boundary**: YouTube is a hard dependency; clearly mark it as outside your trust boundary.
- **Persistent volume boundary**: outputs are durable; container is ephemeral.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% Level 1: System Context
  %% =========================================================
  subgraph "System Context (Level 1)"
    direction TB

    Operator["Operator / User"]:::actor
    Config["recorder.env\n- TARGET\n- CHANNEL or PLAYLIST\n- TITLE_FILTER"]:::config

    subgraph "External YouTube (outside trust boundary)"
      direction TB
      YTMeta["YouTube Metadata Endpoints\n(channel/playlist listing)"]:::external
      YTCDN["YouTube Video/CDN Streaming Endpoints\n(media transfer)"]:::external
    end

    Storage[("Host Storage / Docker Volume\nRecordings under TARGET/…")]:::storage
    Logs["Container Logs (stdout/stderr)"]:::observability

    Compose["Docker Compose Stack\n(docker-compose.yml)"]:::compose
    Service["Service: youtube-live-recorder"]:::compose
  end

  Operator -->|"start/stop;configure"| Compose
  Config -->|"inject_env"| Compose
  Compose -->|"runs"| Service

  Service -->|"poll_metadata"| YTMeta
  Service -->|"download/record_media"| YTCDN
  Service -->|"write_files"| Storage
  Service -->|"emit_logs"| Logs

  %% =========================================================
  %% Level 2: Container Diagram (Docker Compose centered)
  %% =========================================================
  subgraph "Container Diagram (Level 2)"
    direction TB

    subgraph "youtube-live-recorder service (container)"
      direction TB

      Image["Recorder Service Container Image\n(root Dockerfile)"]:::container
      Entrypoint["Startup Orchestrator\n(entrypoint.sh)"]:::orchestrator

      subgraph "Runtime Processes (logical components)"
        direction TB
        Watcher["Watcher Process (Node/TS)\n(watch-new-movie)"]:::component
        Recorder["Recorder / Downloader Process\n(headless worker)"]:::component
        Toolchain["YouTube Download/Record CLI Toolchain\n(packaged in image)"]:::tooling
        FSWriter["Filesystem Writer\n(TARGET-based organization)"]:::component
        LocalState[("Local State Store\n(seen IDs / dedup)")]:::storage
      end
    end
  end

  Image -->|"contains"| Entrypoint
  Entrypoint -->|"start_loop"| Watcher
  Entrypoint -->|"prepare_env_and_paths"| FSWriter

  Watcher -->|"trigger_recording(videoId/url)"| Recorder
  Recorder -->|"exec"| Toolchain
  Toolchain -->|"fetch_media"| YTCDN
  Watcher -->|"list/check_latest"| YTMeta

  Watcher -->|"read/write_dedup"| LocalState
  LocalState -->|"store_under_TARGET"| Storage

  Recorder -->|"write_outputs"| FSWriter
  FSWriter -->|"persist"| Storage

  Watcher -->|"log_events"| Logs
  Recorder -->|"log_events"| Logs
  Entrypoint -->|"log_startup"| Logs

  %% =========================================================
  %% Level 3: Component Diagram (Watcher internals - conceptual)
  %% =========================================================
  subgraph "Watcher Component Detail (Level 3) — watch-new-movie"
    direction TB

    WMain["Watcher Main Entrypoint\n(src/main.ts)"]:::component

    subgraph "Watcher Modules (conceptual)"
      direction TB
      WConfig["Config Loader\n(read/validate env)"]:::component
      WDiscovery["YouTube Discovery Client\n(fetch + normalize candidates)"]:::component
      WFilter["Filter Engine\n(apply TITLE_FILTER)"]:::component
      WDedup["State / De-duplication\n(idempotency by videoId)"]:::component
      WTrigger["Job Trigger / Orchestrator\n(shell exec; concurrency control)"]:::component
      WLog["Logging/Telemetry\n(stdout)"]:::observability
    end
  end

  Watcher -->|"implemented_by"| WMain
  WMain -->|"load_config"| WConfig
  WConfig -->|"options"| WDiscovery
  WDiscovery -->|"candidates"| WFilter
  WFilter -->|"matches"| WDedup
  WDedup -->|"new_video?"| WTrigger
  WTrigger -->|"invoke_recorder"| Recorder
  WTrigger -->|"use_toolchain"| Toolchain
  WDiscovery -->|"metadata_requests"| YTMeta
  WDedup -->|"persist_state"| LocalState
  WMain -->|"logs"| WLog
  WLog -->|"container_logs"| Logs

  %% =========================================================
  %% CI/CD Lane (GitHub Actions)
  %% =========================================================
  subgraph "CI/CD (GitHub Actions)"
    direction TB
    GHRepo["Repository"]:::cicd
    Workflows["GitHub Workflows\n(.github/workflows/)"]:::cicd
    DockerWF["Docker Build/Publish\n(docker.yml)"]:::cicd
    NodeWF["Node/TypeScript CI\n(nodejs-ci.yml)"]:::cicd
    ShellWF["Shell Script CI\n(shell-ci.yml)"]:::cicd
    HadoWF["Dockerfile Lint\n(hadolint-ci.yml)"]:::cicd
    ImageOut["Published Container Image\n(used by Compose)"]:::registry
  end

  GHRepo -->|"triggers"| Workflows
  Workflows -->|"runs"| DockerWF
  Workflows -->|"runs"| NodeWF
  Workflows -->|"runs"| ShellWF
  Workflows -->|"runs"| HadoWF
  DockerWF -->|"build_and_publish"| ImageOut
  ImageOut -->|"pulled_by"| Compose

  %% =========================================================
  %% Hidden nodes solely to attach click events cleanly (not connected)
  %% =========================================================
  WatcherImage["Watcher Container Image (watch-new-movie/Dockerfile)"]:::hidden
  WatcherEntrypoint["Watcher Entrypoint (watch-new-movie/entrypoint.sh)"]:::hidden
  WatcherPkg["Watcher package.json (deps/scripts)"]:::hidden

  %% =========================================================
  %% Click Events (from component_mapping)
  %% =========================================================
  click Compose "https://github.com/book000/youtube-live-recorder/blob/master/docker-compose.yml"
  click Image "https://github.com/book000/youtube-live-recorder/tree/master/Dockerfile"
  click Entrypoint "https://github.com/book000/youtube-live-recorder/blob/master/entrypoint.sh"
  click Watcher "https://github.com/book000/youtube-live-recorder/tree/master/watch-new-movie/"
  click WMain "https://github.com/book000/youtube-live-recorder/blob/master/watch-new-movie/src/main.ts"
  click Toolchain "https://github.com/book000/youtube-live-recorder/tree/master/Dockerfile"
  click Workflows "https://github.com/book000/youtube-live-recorder/tree/master/.github/workflows/"
  click DockerWF "https://github.com/book000/youtube-live-recorder/blob/master/.github/workflows/docker.yml"
  click NodeWF "https://github.com/book000/youtube-live-recorder/blob/master/.github/workflows/nodejs-ci.yml"
  click ShellWF "https://github.com/book000/youtube-live-recorder/blob/master/.github/workflows/shell-ci.yml"
  click HadoWF "https://github.com/book000/youtube-live-recorder/blob/master/.github/workflows/hadolint-ci.yml"

  %% Additional mapped watcher files
  click WConfig "https://github.com/book000/youtube-live-recorder/tree/master/watch-new-movie/"
  click WDiscovery "https://github.com/book000/youtube-live-recorder/tree/master/watch-new-movie/"
  click WFilter "https://github.com/book000/youtube-live-recorder/tree/master/watch-new-movie/"
  click WDedup "https://github.com/book000/youtube-live-recorder/tree/master/watch-new-movie/"
  click WTrigger "https://github.com/book000/youtube-live-recorder/tree/master/watch-new-movie/"
  click WLog "https://github.com/book000/youtube-live-recorder/tree/master/watch-new-movie/"
  click WatcherImage "https://github.com/book000/youtube-live-recorder/tree/master/watch-new-movie/Dockerfile"
  click WatcherEntrypoint "https://github.com/book000/youtube-live-recorder/blob/master/watch-new-movie/entrypoint.sh"
  click WatcherPkg "https://github.com/book000/youtube-live-recorder/blob/master/watch-new-movie/package.json"

  %% =========================================================
  %% Styles
  %% =========================================================
  classDef actor fill:#E3F2FD,stroke:#1565C0,stroke-width:1px,color:#0D47A1
  classDef external fill:#FFEBEE,stroke:#C62828,stroke-width:1px,color:#7F0000
  classDef compose fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px,color:#1B5E20
  classDef container fill:#E0F7FA,stroke:#006064,stroke-width:1px,color:#00363A
  classDef orchestrator fill:#FFF8E1,stroke:#FF8F00,stroke-width:1px,color:#E65100
  classDef component fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px,color:#4A148C
  classDef tooling fill:#E1F5FE,stroke:#0277BD,stroke-width:1px,color:#01579B
  classDef storage fill:#F1F8E9,stroke:#558B2F,stroke-width:1px,color:#33691E
  classDef config fill:#FFF3E0,stroke:#EF6C00,stroke-width:1px,color:#E65100
  classDef observability fill:#ECEFF1,stroke:#455A64,stroke-width:1px,color:#263238
  classDef cicd fill:#E8EAF6,stroke:#283593,stroke-width:1px,color:#1A237E
  classDef registry fill:#E0F2F1,stroke:#00796B,stroke-width:1px,color:#004D40
  classDef hidden fill:#FFFFFF,stroke:#FFFFFF,color:#FFFFFF
```
