# paulmndn/yt2pod architecture

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

- Interactive diagram: https://gitdiagram.com/paulmndn/yt2pod
- Repository: https://github.com/paulmndn/yt2pod

## Overview

yt2pod is a self-hosted web app that turns playlist or channel subscriptions into podcast feeds. Users manage subscription settings in the web UI; checks can be queued manually or run on a schedule. The worker runs yt-dlp downloads, records episodes and channel metadata, and the app serves RSS feeds and media files to podcast apps. SQLite stores subscriptions, episodes, and check status. The README documents the broader capabilities; the source excerpts show the principal calls, but not every UI template or integration detail.

Main entry points: [`yt2pod/__init__.py`](https://github.com/paulmndn/yt2pod/blob/main/yt2pod/__init__.py) (Web routes), [`yt2pod/downloader.py`](https://github.com/paulmndn/yt2pod/blob/main/yt2pod/downloader.py) (Download processing), [`yt2pod/worker.py`](https://github.com/paulmndn/yt2pod/blob/main/yt2pod/worker.py) (Check scheduler), [`yt2pod/db.py`](https://github.com/paulmndn/yt2pod/blob/main/yt2pod/db.py) (SQLite database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_entry["App startup<br/>[__main__.py]"]
  node_routes["Web routes<br/>[__init__.py]"]
  node_templates["Web templates"]
end

subgraph group_checks["Subscription checks"]
  node_worker["Check scheduler<br/>[worker.py]"]
  node_downloader["Download processing<br/>[downloader.py]"]
end

subgraph group_storage["Persistence and files"]
  node_database[("SQLite database<br/>[db.py]")]
  node_downloads["Downloaded media<br/>[downloader.py]"]
end

subgraph group_delivery["Podcast delivery"]
  node_feedbuilder["RSS generation<br/>[feeds.py]"]
  node_feed["Subscription feed<br/>[__init__.py]"]
  node_media["Media endpoint<br/>[__init__.py]"]
end

node_browser(("Browser user"))
node_podcast(("Podcast app"))
node_ytdlp["yt-dlp"]
node_youtube["YouTube"]

node_entry -->|"starts app"| node_routes
node_routes -->|"renders"| node_templates
node_browser -->|"manages subscriptions"| node_routes
node_routes -->|"reads and writes"| node_database
node_routes -->|"queues checks"| node_worker
node_entry -->|"starts worker"| node_worker
node_worker -->|"lists enabled IDs"| node_database
node_worker -->|"runs subscription"| node_downloader
node_downloader -->|"checks and records episodes"| node_database
node_downloader -->|"configures and runs"| node_ytdlp
node_ytdlp -->|"fetches playlist videos"| node_youtube
node_downloader -->|"writes media files"| node_downloads
node_routes -->|"builds RSS"| node_feedbuilder
node_feedbuilder -->|"generates XML"| node_feed
node_routes -->|"loads feed episodes"| node_database
node_podcast -->|"fetches feed"| node_feed
node_podcast -->|"fetches enclosures"| node_media
node_routes -->|"serves files"| node_media
node_media -->|"reads media files"| node_downloads

click node_entry "https://github.com/paulmndn/yt2pod/blob/main/yt2pod/__main__.py"
click node_routes "https://github.com/paulmndn/yt2pod/blob/main/yt2pod/__init__.py"
click node_templates "https://github.com/paulmndn/yt2pod/tree/main/yt2pod/templates"
click node_worker "https://github.com/paulmndn/yt2pod/blob/main/yt2pod/worker.py"
click node_downloader "https://github.com/paulmndn/yt2pod/blob/main/yt2pod/downloader.py"
click node_database "https://github.com/paulmndn/yt2pod/blob/main/yt2pod/db.py"
click node_downloads "https://github.com/paulmndn/yt2pod/blob/main/yt2pod/downloader.py"
click node_feedbuilder "https://github.com/paulmndn/yt2pod/blob/main/yt2pod/feeds.py"
click node_feed "https://github.com/paulmndn/yt2pod/blob/main/yt2pod/__init__.py"
click node_media "https://github.com/paulmndn/yt2pod/blob/main/yt2pod/__init__.py"

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_entry,node_routes,node_templates,node_browser toneBlue
class node_worker,node_downloader toneAmber
class node_database,node_downloads toneMint
class node_feedbuilder,node_feed,node_media toneRose
class node_podcast,node_ytdlp,node_youtube toneIndigo
```

## Components

### Web app

- [App startup](https://github.com/paulmndn/yt2pod/blob/main/yt2pod/__main__.py): `yt2pod/__main__.py`
- [Web routes](https://github.com/paulmndn/yt2pod/blob/main/yt2pod/__init__.py): `yt2pod/__init__.py`
- [Web templates](https://github.com/paulmndn/yt2pod/tree/main/yt2pod/templates): `yt2pod/templates`

### Subscription checks

- [Check scheduler](https://github.com/paulmndn/yt2pod/blob/main/yt2pod/worker.py): `yt2pod/worker.py`
- [Download processing](https://github.com/paulmndn/yt2pod/blob/main/yt2pod/downloader.py): `yt2pod/downloader.py`

### Persistence and files

- [SQLite database](https://github.com/paulmndn/yt2pod/blob/main/yt2pod/db.py): `yt2pod/db.py`
- [Downloaded media](https://github.com/paulmndn/yt2pod/blob/main/yt2pod/downloader.py): `yt2pod/downloader.py`

### Podcast delivery

- [RSS generation](https://github.com/paulmndn/yt2pod/blob/main/yt2pod/feeds.py): `yt2pod/feeds.py`
- [Subscription feed](https://github.com/paulmndn/yt2pod/blob/main/yt2pod/__init__.py): `yt2pod/__init__.py`
- [Media endpoint](https://github.com/paulmndn/yt2pod/blob/main/yt2pod/__init__.py): `yt2pod/__init__.py`

### Other components

- **Browser user**
- **Podcast app**
- **yt-dlp**
- **YouTube**

## Connections

- App startup → Web routes: starts app (evidence: `yt2pod/__main__.py`)
- Web routes → Web templates: renders (evidence: `yt2pod/__init__.py`)
- Browser user → Web routes: manages subscriptions (evidence: `README.md`)
- Web routes → SQLite database: reads and writes (evidence: `yt2pod/__init__.py`)
- Web routes → Check scheduler: queues checks (evidence: `yt2pod/__init__.py`)
- App startup → Check scheduler: starts worker (evidence: `yt2pod/__main__.py`)
- Check scheduler → SQLite database: lists enabled IDs (evidence: `yt2pod/worker.py`)
- Check scheduler → Download processing: runs subscription (evidence: `yt2pod/worker.py`)
- Download processing → SQLite database: checks and records episodes (evidence: `yt2pod/downloader.py`)
- Download processing → yt-dlp: configures and runs (evidence: `yt2pod/downloader.py`)
- yt-dlp → YouTube: fetches playlist videos (evidence: `README.md`)
- Download processing → Downloaded media: writes media files (evidence: `README.md`)
- Web routes → RSS generation: builds RSS (evidence: `yt2pod/__init__.py`)
- RSS generation → Subscription feed: generates XML (evidence: `yt2pod/feeds.py`)
- Web routes → SQLite database: loads feed episodes (evidence: `yt2pod/__init__.py`)
- Podcast app → Subscription feed: fetches feed (evidence: `README.md`)
- Podcast app → Media endpoint: fetches enclosures (evidence: `README.md`)
- Web routes → Media endpoint: serves files (evidence: `yt2pod/__init__.py`)
- Media endpoint → Downloaded media: reads media files (evidence: `yt2pod/__init__.py`)
