# orcalinux/youtube-downloader architecture

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

- Interactive diagram: https://gitdiagram.com/orcalinux/youtube-downloader
- Repository: https://github.com/orcalinux/youtube-downloader

## Overview

##### Project type and purpose
- This is a command‐line YouTube video/playlist downloader written in Python.
- It supports interactive prompts (via Rich), graceful Ctrl+C handling, logging, and a Dockerized runtime.

##### File structure
- Top‐level scripts:
- main.py – entry point, orchestrates prompts and download flow
- downloader.py – core logic for fetching and saving videos/playlists
- utils.py – safe_prompt wrappers, interrupt handlers
- config.py – default paths, quality profiles, logging setup
- DevOps & build files:
- Dockerfile / .dockerignore – container image definition
- Makefile – local venv creation, ffmpeg checks, run targets, docker-run shortcut
- requirements.txt/.in – Python dependencies
- Other: LICENSE, README.md, downloader.log (runtime artifact), .gitignore

##### README for additional insights
- Interactive modes: single video vs. playlist, quality selection.
- Graceful SIGINT handling with user-friendly messages and log entries.
- Docker support with optional host-volume bind for downloads.
- Logging to console and `downloader.log`.
- External dependencies: YouTube servers (HTTP), ffmpeg CLI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User (CLI)"]:::external

    %% CLI Interface Layer
    subgraph "CLI Interface Layer"
        direction TB
        Main["main.py"]:::internal
        Utils["utils.py"]:::internal
    end

    %% Download Engine
    subgraph "Download Engine"
        direction TB
        Engine["downloader.py"]:::internal
        Config["config.py"]:::internal
    end

    %% External Services
    subgraph "External Services"
        direction TB
        YouTube["YouTube HTTP"]:::external
        FFMPEG["ffmpeg CLI"]:::external
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        FS["Local Filesystem"]:::datastore
        LogFile["downloader.log"]:::datastore
    end

    %% Runtime Environments
    subgraph "Runtime Environments"
        direction TB
        Venv["Local Python venv"]:::runtime
        DockerBoundary["Docker Container"]:::runtime
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        direction TB
        DockerfileNode["Dockerfile / .dockerignore"]:::devops
        MakefileNode["Makefile"]:::devops
        RequirementsIn["requirements.in"]:::devops
        RequirementsTxt["requirements.txt"]:::devops
        Readme["README.md"]:::devops
        License["LICENSE"]:::devops
        Gitignore[".gitignore"]:::devops
    end

    %% Relationships
    User -->|"selects mode, URL, quality"| Main
    Main -->|"uses prompts"| Utils
    Main -->|"calls download"| Engine
    Engine -->|"reads settings"| Config
    Engine -->|"fetches streams"| YouTube
    Engine -->|"spawns process"| FFMPEG
    Engine -->|"writes files"| FS
    Engine -->|"logs events"| LogFile
    Utils -->|"handles interrupts & logs"| LogFile

    Venv --> Main
    Venv --> Engine
    DockerBoundary --> Main
    DockerBoundary --> Engine
    DockerBoundary -.->|mounts volume| FS

    DockerfileNode -->|defines| DockerBoundary
    MakefileNode -->|runs local or docker| Venv
    MakefileNode -->|runs local or docker| DockerBoundary
    RequirementsIn -->|pins deps| RequirementsTxt

    %% Click Events
    click Main "https://github.com/orcalinux/youtube-downloader/blob/main/main.py"
    click Utils "https://github.com/orcalinux/youtube-downloader/blob/main/utils.py"
    click Engine "https://github.com/orcalinux/youtube-downloader/blob/main/downloader.py"
    click Config "https://github.com/orcalinux/youtube-downloader/blob/main/config.py"
    click DockerfileNode "https://github.com/orcalinux/youtube-downloader/tree/main/Dockerfile"
    click DockerfileNode "https://github.com/orcalinux/youtube-downloader/blob/main/.dockerignore"
    click MakefileNode "https://github.com/orcalinux/youtube-downloader/tree/main/Makefile"
    click RequirementsIn "https://github.com/orcalinux/youtube-downloader/blob/main/requirements.in"
    click RequirementsTxt "https://github.com/orcalinux/youtube-downloader/blob/main/requirements.txt"
    click Readme "https://github.com/orcalinux/youtube-downloader/blob/main/README.md"
    click License "https://github.com/orcalinux/youtube-downloader/tree/main/LICENSE"
    click Gitignore "https://github.com/orcalinux/youtube-downloader/blob/main/.gitignore"
    click LogFile "https://github.com/orcalinux/youtube-downloader/blob/main/downloader.log"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef external fill:#DFF2D8,stroke:#22863A,color:#22863A;
    classDef datastore fill:#FFE8A1,stroke:#D29700,color:#D29700,stroke-dasharray: 5 5;
    classDef devops fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef runtime fill:#E8DFFF,stroke:#6F42C1,color:#6F42C1;
```
