# takacsrichard/ytq architecture

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

- Interactive diagram: https://gitdiagram.com/takacsrichard/ytq
- Repository: https://github.com/takacsrichard/ytq

## Overview

This repository is a yt-dlp queue daemon. Its visible workflow is daemon startup and recovery, polling a SQLite queue, claiming pending URLs in dynamically scaled workers, invoking yt-dlp, and recording outcomes; it also cleans partial files after failures or interrupted work. The single source file combines these responsibilities. The excerpts are partial, so the graph omits unshown implementation details and does not infer any separate queue-submission interface.

Main entry points: [`daemon.py`](https://github.com/takacsrichard/ytq/blob/main/daemon.py) (yt-dlp execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Daemon orchestration"]
  node_daemon["Daemon lifecycle<br/>[daemon.py]"]
  node_scheduler["Polling and scaling<br/>[daemon.py]"]
  node_workers["Worker threads<br/>[daemon.py]"]
end

subgraph group_queue["Queue state"]
  node_sqlite[("SQLite queue<br/>[daemon.py]")]
  node_claim["Claim and status<br/>[daemon.py]"]
end

subgraph group_downloads["Download processing"]
  node_downloader["yt-dlp execution<br/>[daemon.py]"]
  node_cleanup["Partial-file cleanup<br/>[daemon.py]"]
end

node_yt_dlp["yt-dlp"]

node_daemon -->|"initializes and recovers"| node_sqlite
node_daemon -->|"starts loop"| node_scheduler
node_scheduler -->|"counts statuses"| node_sqlite
node_scheduler -->|"scales workers"| node_workers
node_workers -->|"claims pending items"| node_claim
node_claim -->|"reads and updates"| node_sqlite
node_workers -->|"processes claimed item"| node_downloader
node_downloader -->|"runs subprocess"| node_yt_dlp
node_downloader -->|"records outcome"| node_sqlite
node_downloader -->|"cleans after failure"| node_cleanup
node_daemon -->|"cleans interrupted work"| node_cleanup

click node_daemon "https://github.com/takacsrichard/ytq/blob/main/daemon.py"
click node_scheduler "https://github.com/takacsrichard/ytq/blob/main/daemon.py"
click node_workers "https://github.com/takacsrichard/ytq/blob/main/daemon.py"
click node_sqlite "https://github.com/takacsrichard/ytq/blob/main/daemon.py"
click node_claim "https://github.com/takacsrichard/ytq/blob/main/daemon.py"
click node_downloader "https://github.com/takacsrichard/ytq/blob/main/daemon.py"
click node_cleanup "https://github.com/takacsrichard/ytq/blob/main/daemon.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_daemon,node_scheduler,node_workers toneBlue
class node_sqlite,node_claim toneAmber
class node_downloader,node_cleanup toneMint
class node_yt_dlp toneIndigo
```

## Components

### Daemon orchestration

- [Daemon lifecycle](https://github.com/takacsrichard/ytq/blob/main/daemon.py): `daemon.py`
- [Polling and scaling](https://github.com/takacsrichard/ytq/blob/main/daemon.py): `daemon.py`
- [Worker threads](https://github.com/takacsrichard/ytq/blob/main/daemon.py): `daemon.py`

### Queue state

- [SQLite queue](https://github.com/takacsrichard/ytq/blob/main/daemon.py): `daemon.py`
- [Claim and status](https://github.com/takacsrichard/ytq/blob/main/daemon.py): `daemon.py`

### Download processing

- [yt-dlp execution](https://github.com/takacsrichard/ytq/blob/main/daemon.py): `daemon.py`
- [Partial-file cleanup](https://github.com/takacsrichard/ytq/blob/main/daemon.py): `daemon.py`

### Other components

- **yt-dlp**

## Connections

- Daemon lifecycle → SQLite queue: initializes and recovers (evidence: `daemon.py`)
- Daemon lifecycle → Polling and scaling: starts loop (evidence: `daemon.py`)
- Polling and scaling → SQLite queue: counts statuses (evidence: `daemon.py`)
- Polling and scaling → Worker threads: scales workers (evidence: `daemon.py`)
- Worker threads → Claim and status: claims pending items (evidence: `daemon.py`)
- Claim and status → SQLite queue: reads and updates (evidence: `daemon.py`)
- Worker threads → yt-dlp execution: processes claimed item (evidence: `daemon.py`)
- yt-dlp execution → yt-dlp: runs subprocess (evidence: `daemon.py`)
- yt-dlp execution → SQLite queue: records outcome (evidence: `daemon.py`)
- yt-dlp execution → Partial-file cleanup: cleans after failure (evidence: `daemon.py`)
- Daemon lifecycle → Partial-file cleanup: cleans interrupted work (evidence: `daemon.py`)
