# alexta69/metube architecture

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

- Interactive diagram: https://gitdiagram.com/alexta69/metube
- Repository: https://github.com/alexta69/metube

## Overview

MeTube is a self-hosted web interface for submitting media URLs and downloading video, audio, subtitles, and related content through yt-dlp. The main workflow runs from the browser UI through the backend API into download processing, with queue/status updates returned to the UI. Separate subscription management periodically discovers new channel or playlist items and queues them. Persistent state and URL safety are important supporting layers. Some backend wiring is unsampled, so uncertain relationships are omitted rather than inferred from imports alone.

Main entry points: [`app/ytdl.py`](https://github.com/alexta69/metube/blob/master/app/ytdl.py) (Download engine), [`ui/src/app/app.ts`](https://github.com/alexta69/metube/blob/master/ui/src/app/app.ts) (Main UI), [`app/subscriptions.py`](https://github.com/alexta69/metube/blob/master/app/subscriptions.py) (Subscription manager), [`app/main.py`](https://github.com/alexta69/metube/blob/master/app/main.py) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser UI"]
  node_appui["Main UI<br/>[app.ts]"]
  node_downloadsvc["Download service"]
  node_socketui["Socket client"]
  node_batch["Batch URL tools"]
  node_subsvc["Subscription service"]
  node_toast["Notifications<br/>[toast.service.ts]"]
end

subgraph group_backend["Download backend"]
  node_api["HTTP API<br/>[main.py]"]
  node_download["Download engine<br/>[ytdl.py]"]
  node_formats["Format selection<br/>[dl_formats.py]"]
  node_metadata["Music metadata<br/>[music_metadata.py]"]
  node_queue["Persistent queue<br/>[ytdl.py]"]
end

subgraph group_subs["Subscriptions"]
  node_subscription["Subscription manager<br/>[subscriptions.py]"]
end

subgraph group_support["State and safety"]
  node_state[("State store<br/>[state_store.py]")]
  node_urlguard["URL safety<br/>[url_guard.py]"]
  node_tasks["Background tasks<br/>[bg_tasks.py]"]
end

node_user(("User"))
node_media(("Media sites"))
node_filesystem[("Download files")]

node_user -->|"submits URLs"| node_appui
node_appui -->|"adds downloads"| node_downloadsvc
node_appui -->|"manages subscriptions"| node_subsvc
node_appui -->|"exports URLs"| node_batch
node_downloadsvc -->|"receives events"| node_socketui
node_subsvc -->|"receives events"| node_socketui
node_appui -->|"shows notices"| node_toast
node_downloadsvc -.->|"posts requests"| node_api
node_subsvc -.->|"posts requests"| node_api
node_api -->|"checks subscriptions"| node_subscription
node_api -.->|"dispatches downloads"| node_download
node_subscription -->|"queues new items"| node_queue
node_subscription -->|"persists records"| node_state
node_subscription -->|"starts periodic loop"| node_tasks
node_subscription -.->|"checks channels"| node_media
node_download -->|"extracts media"| node_media
node_download -->|"selects format"| node_formats
node_download -->|"writes downloads"| node_filesystem
node_download -.->|"validates URLs"| node_urlguard
node_download -.->|"processes audio tags"| node_metadata
node_download -->|"tracks work"| node_queue

click node_appui "https://github.com/alexta69/metube/blob/master/ui/src/app/app.ts"
click node_downloadsvc "https://github.com/alexta69/metube/blob/master/ui/src/app/services/downloads.service.ts"
click node_socketui "https://github.com/alexta69/metube/blob/master/ui/src/app/services/metube-socket.service.ts"
click node_batch "https://github.com/alexta69/metube/blob/master/ui/src/app/services/batch-urls.service.ts"
click node_subsvc "https://github.com/alexta69/metube/blob/master/ui/src/app/services/subscriptions.service.ts"
click node_toast "https://github.com/alexta69/metube/blob/master/ui/src/app/services/toast.service.ts"
click node_api "https://github.com/alexta69/metube/blob/master/app/main.py"
click node_download "https://github.com/alexta69/metube/blob/master/app/ytdl.py"
click node_formats "https://github.com/alexta69/metube/blob/master/app/dl_formats.py"
click node_metadata "https://github.com/alexta69/metube/blob/master/app/music_metadata.py"
click node_subscription "https://github.com/alexta69/metube/blob/master/app/subscriptions.py"
click node_queue "https://github.com/alexta69/metube/blob/master/app/ytdl.py"
click node_state "https://github.com/alexta69/metube/blob/master/app/state_store.py"
click node_urlguard "https://github.com/alexta69/metube/blob/master/app/url_guard.py"
click node_tasks "https://github.com/alexta69/metube/blob/master/app/bg_tasks.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_appui,node_downloadsvc,node_socketui,node_batch,node_subsvc,node_toast,node_user toneBlue
class node_api,node_download,node_formats,node_metadata,node_queue,node_filesystem toneAmber
class node_subscription toneMint
class node_state,node_urlguard,node_tasks toneRose
class node_media toneIndigo
```

## Components

### Browser UI

- [Main UI](https://github.com/alexta69/metube/blob/master/ui/src/app/app.ts): `ui/src/app/app.ts`
- [Download service](https://github.com/alexta69/metube/blob/master/ui/src/app/services/downloads.service.ts): `ui/src/app/services/downloads.service.ts`
- [Socket client](https://github.com/alexta69/metube/blob/master/ui/src/app/services/metube-socket.service.ts): `ui/src/app/services/metube-socket.service.ts`
- [Batch URL tools](https://github.com/alexta69/metube/blob/master/ui/src/app/services/batch-urls.service.ts): `ui/src/app/services/batch-urls.service.ts`
- [Subscription service](https://github.com/alexta69/metube/blob/master/ui/src/app/services/subscriptions.service.ts): `ui/src/app/services/subscriptions.service.ts`
- [Notifications](https://github.com/alexta69/metube/blob/master/ui/src/app/services/toast.service.ts): `ui/src/app/services/toast.service.ts`

### Download backend

- [HTTP API](https://github.com/alexta69/metube/blob/master/app/main.py): `app/main.py`
- [Download engine](https://github.com/alexta69/metube/blob/master/app/ytdl.py): `app/ytdl.py`
- [Format selection](https://github.com/alexta69/metube/blob/master/app/dl_formats.py): `app/dl_formats.py`
- [Music metadata](https://github.com/alexta69/metube/blob/master/app/music_metadata.py): `app/music_metadata.py`
- [Persistent queue](https://github.com/alexta69/metube/blob/master/app/ytdl.py): `app/ytdl.py`

### Subscriptions

- [Subscription manager](https://github.com/alexta69/metube/blob/master/app/subscriptions.py): `app/subscriptions.py`

### State and safety

- [State store](https://github.com/alexta69/metube/blob/master/app/state_store.py): `app/state_store.py`
- [URL safety](https://github.com/alexta69/metube/blob/master/app/url_guard.py): `app/url_guard.py`
- [Background tasks](https://github.com/alexta69/metube/blob/master/app/bg_tasks.py): `app/bg_tasks.py`

### Other components

- **User**
- **Media sites**
- **Download files**

## Connections

- User → Main UI: submits URLs (evidence: `README.md`)
- Main UI → Download service: adds downloads (evidence: `ui/src/app/app.ts`)
- Main UI → Subscription service: manages subscriptions (evidence: `ui/src/app/app.ts`)
- Main UI → Batch URL tools: exports URLs (evidence: `ui/src/app/services/batch-urls.service.ts`)
- Download service → Socket client: receives events (evidence: `ui/src/app/services/downloads.service.ts`)
- Subscription service → Socket client: receives events (evidence: `ui/src/app/services/subscriptions.service.ts`)
- Main UI → Notifications: shows notices (evidence: `ui/src/app/app.ts`)
- Download service → HTTP API: posts requests
- Subscription service → HTTP API: posts requests
- HTTP API → Subscription manager: checks subscriptions (evidence: `app/main.py`)
- HTTP API → Download engine: dispatches downloads (evidence: `app/main.py`)
- Subscription manager → Persistent queue: queues new items (evidence: `app/subscriptions.py`)
- Subscription manager → State store: persists records (evidence: `app/subscriptions.py`)
- Subscription manager → Background tasks: starts periodic loop (evidence: `app/subscriptions.py`)
- Subscription manager → Media sites: checks channels
- Download engine → Media sites: extracts media (evidence: `README.md`)
- Download engine → Format selection: selects format (evidence: `app/ytdl.py`)
- Download engine → Download files: writes downloads (evidence: `README.md`)
- Download engine → URL safety: validates URLs (evidence: `app/ytdl.py`)
- Download engine → Music metadata: processes audio tags (evidence: `app/ytdl.py`)
- Download engine → Persistent queue: tracks work (evidence: `app/ytdl.py`)
