# gidix13579/yt-downloader architecture

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

- Interactive diagram: https://gitdiagram.com/gidix13579/yt-downloader
- Repository: https://github.com/gidix13579/yt-downloader

## Overview

YT Downloader is a local web app for fetching YouTube video or audio onto the device using its browser. The main flow is: submit a YouTube link, inspect available video or playlist information, choose a format and quality, queue a download, then save the completed file (or playlist ZIP). The server also supports LAN/Tailscale access, QR codes, optional PIN protection, and yt-dlp updates. The README documents the browser workflow and capabilities; some frontend and route implementations were not sampled, so those relationships are shown only where documented.

Main entry points: [`server/index.js`](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/index.js) (HTTP API and delivery), [`server/jobs.js`](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/jobs.js) (Download queue), [`public/index.html`](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/public/index.html) (Web interface), [`server/ytdlp.js`](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/ytdlp.js) (YouTube metadata and downloads)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser app"]
  node_browser["Web interface<br/>[index.html]"]
  node_offline["Offline fallback<br/>[sw.js]"]
end

subgraph group_server["HTTP server"]
  node_http["HTTP API and delivery<br/>[index.js]"]
  node_validation["URL validation<br/>[validate.js]"]
end

subgraph group_download["Download processing"]
  node_jobs["Download queue<br/>[jobs.js]"]
  node_ytdlp["YouTube metadata and downloads<br/>[ytdlp.js]"]
  node_zip["Playlist ZIP writer<br/>[zip.js]"]
  node_files[("Temporary download files<br/>[jobs.js]")]
end

subgraph group_access["Access and configuration"]
  node_auth["PIN authentication<br/>[auth.js]"]
  node_settings[("Server settings<br/>[config.js]")]
  node_network["Network discovery<br/>[network.js]"]
  node_qr["QR generation<br/>[qr.js]"]
  node_binaries["Binary detection<br/>[bins.js]"]
end

node_user(("User"))
node_youtube{{"YouTube"}}
node_ytbinary{{"yt-dlp"}}
node_ffmpeg{{"ffmpeg"}}
node_device(("Client device"))

node_user -->|"submits link"| node_browser
node_browser -->|"requests information and downloads"| node_http
node_http -->|"validates links"| node_validation
node_http -->|"checks access"| node_auth
node_http -->|"routes job actions"| node_jobs
node_http -->|"serves QR"| node_qr
node_http -->|"gets network addresses"| node_network
node_http -->|"loads and saves settings"| node_settings
node_http -->|"requests video information"| node_ytdlp
node_jobs -->|"runs downloads"| node_ytdlp
node_jobs -->|"sanitizes filenames"| node_validation
node_jobs -->|"builds playlist archive"| node_zip
node_jobs -->|"writes and cleans up"| node_files
node_http -->|"streams completed files"| node_files
node_ytdlp -.->|"spawns"| node_ytbinary
node_ytbinary -->|"fetches media"| node_youtube
node_ytbinary -->|"uses for media processing"| node_ffmpeg
node_device -->|"connects over LAN or Tailscale"| node_http
node_http -.->|"provides application"| node_browser
node_browser -.->|"uses service worker"| node_offline

click node_browser "https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/public/index.html"
click node_offline "https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/public/sw.js"
click node_http "https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/index.js"
click node_validation "https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/validate.js"
click node_auth "https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/auth.js"
click node_settings "https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/config.js"
click node_network "https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/network.js"
click node_qr "https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/qr.js"
click node_binaries "https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/bins.js"
click node_jobs "https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/jobs.js"
click node_ytdlp "https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/ytdlp.js"
click node_zip "https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/zip.js"
click node_files "https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/jobs.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_offline,node_user,node_device toneBlue
class node_http,node_validation toneAmber
class node_jobs,node_ytdlp,node_zip,node_files toneMint
class node_auth,node_settings,node_network,node_qr,node_binaries toneRose
class node_youtube,node_ytbinary,node_ffmpeg toneIndigo
```

## Components

### Browser app

- [Web interface](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/public/index.html): `public/index.html`
- [Offline fallback](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/public/sw.js): `public/sw.js`

### HTTP server

- [HTTP API and delivery](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/index.js): `server/index.js`
- [URL validation](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/validate.js): `server/validate.js`

### Download processing

- [Download queue](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/jobs.js): `server/jobs.js`
- [YouTube metadata and downloads](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/ytdlp.js): `server/ytdlp.js`
- [Playlist ZIP writer](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/zip.js): `server/zip.js`
- [Temporary download files](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/jobs.js): `server/jobs.js`

### Access and configuration

- [PIN authentication](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/auth.js): `server/auth.js`
- [Server settings](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/config.js): `server/config.js`
- [Network discovery](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/network.js): `server/network.js`
- [QR generation](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/qr.js): `server/qr.js`
- [Binary detection](https://github.com/gidix13579/yt-downloader/blob/claude/youtube-downloader-app-w8cnxk/server/bins.js): `server/bins.js`

### Other components

- **User**
- **YouTube**
- **yt-dlp**
- **ffmpeg**
- **Client device**

## Connections

- User → Web interface: submits link (evidence: `README.md`)
- Web interface → HTTP API and delivery: requests information and downloads (evidence: `README.md`)
- HTTP API and delivery → URL validation: validates links (evidence: `server/index.js`)
- HTTP API and delivery → PIN authentication: checks access (evidence: `server/index.js`)
- HTTP API and delivery → Download queue: routes job actions (evidence: `server/index.js`)
- HTTP API and delivery → QR generation: serves QR (evidence: `server/index.js`)
- HTTP API and delivery → Network discovery: gets network addresses (evidence: `server/index.js`)
- HTTP API and delivery → Server settings: loads and saves settings (evidence: `server/index.js`)
- HTTP API and delivery → YouTube metadata and downloads: requests video information (evidence: `README.md`)
- Download queue → YouTube metadata and downloads: runs downloads (evidence: `server/jobs.js`)
- Download queue → URL validation: sanitizes filenames (evidence: `server/jobs.js`)
- Download queue → Playlist ZIP writer: builds playlist archive (evidence: `server/jobs.js`)
- Download queue → Temporary download files: writes and cleans up (evidence: `server/jobs.js`)
- HTTP API and delivery → Temporary download files: streams completed files (evidence: `server/index.js`)
- YouTube metadata and downloads → yt-dlp: spawns
- yt-dlp → YouTube: fetches media (evidence: `README.md`)
- yt-dlp → ffmpeg: uses for media processing (evidence: `README.md`)
- Client device → HTTP API and delivery: connects over LAN or Tailscale (evidence: `README.md`)
- HTTP API and delivery → Web interface: provides application
- Web interface → Offline fallback: uses service worker
