# dezealous/tubeindex architecture

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

- Interactive diagram: https://gitdiagram.com/dezealous/tubeindex
- Repository: https://github.com/dezealous/tubeindex

## Overview

TubeIndex is a metadata catalogue for YouTube channels. A user submits a handle, channel/video URL, legacy name, or channel ID; the API resolves the channel, fetches and enriches its catalogue, caches results, and streams pages to the browser. The browser can filter and sort results and request TXT, CSV, or JSON exports. Separate capabilities include date-range extraction, RSS-assisted change detection, quota tracking, and rate limiting. The excerpts show the principal endpoint ownership and several service calls; unsampled UI and endpoint details are represented only where documented.

Main entry points: [`app/main.py`](https://github.com/dezealous/tubeindex/blob/main/app/main.py) (HTTP API), [`app/quota.py`](https://github.com/dezealous/tubeindex/blob/main/app/quota.py) (Quota guard), [`app/cache.py`](https://github.com/dezealous/tubeindex/blob/main/app/cache.py) (SQLite catalogue), [`app/streaming.py`](https://github.com/dezealous/tubeindex/blob/main/app/streaming.py) (Video streaming)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interface"]
  node_browser["Catalogue browser<br/>[app.js]"]
end

subgraph group_catalogue["Catalogue workflow"]
  node_api["HTTP API<br/>[main.py]"]
  node_resolver["Input resolver<br/>[resolver.py]"]
  node_youtube["YouTube client<br/>[youtube.py]"]
  node_stream["Video streaming<br/>[streaming.py]"]
  node_cache[("SQLite catalogue<br/>[cache.py]")]
  node_models["Domain schemas<br/>[models.py]"]
end

subgraph group_controls["Quota and access"]
  node_quota["Quota guard<br/>[quota.py]"]
  node_ratelimit["Request limiter<br/>[ratelimit.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_monitoring["Exports and monitoring"]
  node_export["Export generator<br/>[exports.py]"]
  node_diff["Change detection<br/>[diff.py]"]
end

node_user(("Channel user"))
node_ytapi{{"YouTube Data API"}}
node_rss{{"YouTube RSS feed"}}

node_user -->|"submits input"| node_browser
node_browser -->|"requests catalogue"| node_api
node_api -->|"resolves input"| node_resolver
node_resolver -->|"looks up channel"| node_youtube
node_resolver -->|"stores channel"| node_cache
node_resolver -->|"charges lookup"| node_quota
node_youtube -->|"requests metadata"| node_ytapi
node_api -->|"starts stream"| node_stream
node_stream -->|"fetches pages"| node_youtube
node_stream -->|"reads and writes"| node_cache
node_stream -->|"checks and charges"| node_quota
node_stream -->|"streams SSE pages"| node_browser
node_api -->|"loads export data"| node_cache
node_api -->|"enriches videos"| node_youtube
node_api -->|"guards enrichment"| node_quota
node_api -->|"generates export"| node_export
node_export -->|"streams stored rows"| node_cache
node_api -->|"runs diff"| node_diff
node_diff -->|"checks recent IDs"| node_rss
node_diff -->|"reads and updates"| node_cache
node_diff -->|"refreshes catalogue"| node_youtube
node_diff -->|"checks and charges"| node_quota
node_api -->|"configures middleware"| node_ratelimit
node_ratelimit -.->|"uses limits"| node_config
node_quota -->|"records quota"| node_cache
node_quota -->|"reads budget"| node_config

click node_browser "https://github.com/dezealous/tubeindex/blob/main/static/app.js"
click node_api "https://github.com/dezealous/tubeindex/blob/main/app/main.py"
click node_resolver "https://github.com/dezealous/tubeindex/blob/main/app/resolver.py"
click node_youtube "https://github.com/dezealous/tubeindex/blob/main/app/youtube.py"
click node_stream "https://github.com/dezealous/tubeindex/blob/main/app/streaming.py"
click node_cache "https://github.com/dezealous/tubeindex/blob/main/app/cache.py"
click node_models "https://github.com/dezealous/tubeindex/blob/main/app/models.py"
click node_quota "https://github.com/dezealous/tubeindex/blob/main/app/quota.py"
click node_ratelimit "https://github.com/dezealous/tubeindex/blob/main/app/ratelimit.py"
click node_config "https://github.com/dezealous/tubeindex/blob/main/app/config.py"
click node_export "https://github.com/dezealous/tubeindex/blob/main/app/exports.py"
click node_diff "https://github.com/dezealous/tubeindex/blob/main/app/diff.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_browser,node_user toneBlue
class node_api,node_resolver,node_youtube,node_stream,node_cache,node_models toneAmber
class node_quota,node_ratelimit,node_config,node_ytapi toneMint
class node_export,node_diff toneRose
class node_rss toneIndigo
```

## Components

### User interface

- [Catalogue browser](https://github.com/dezealous/tubeindex/blob/main/static/app.js): `static/app.js`

### Catalogue workflow

- [HTTP API](https://github.com/dezealous/tubeindex/blob/main/app/main.py): `app/main.py`
- [Input resolver](https://github.com/dezealous/tubeindex/blob/main/app/resolver.py): `app/resolver.py`
- [YouTube client](https://github.com/dezealous/tubeindex/blob/main/app/youtube.py): `app/youtube.py`
- [Video streaming](https://github.com/dezealous/tubeindex/blob/main/app/streaming.py): `app/streaming.py`
- [SQLite catalogue](https://github.com/dezealous/tubeindex/blob/main/app/cache.py): `app/cache.py`
- [Domain schemas](https://github.com/dezealous/tubeindex/blob/main/app/models.py): `app/models.py`

### Quota and access

- [Quota guard](https://github.com/dezealous/tubeindex/blob/main/app/quota.py): `app/quota.py`
- [Request limiter](https://github.com/dezealous/tubeindex/blob/main/app/ratelimit.py): `app/ratelimit.py`
- [Runtime settings](https://github.com/dezealous/tubeindex/blob/main/app/config.py): `app/config.py`

### Exports and monitoring

- [Export generator](https://github.com/dezealous/tubeindex/blob/main/app/exports.py): `app/exports.py`
- [Change detection](https://github.com/dezealous/tubeindex/blob/main/app/diff.py): `app/diff.py`

### Other components

- **Channel user**
- **YouTube Data API**
- **YouTube RSS feed**

## Connections

- Channel user → Catalogue browser: submits input (evidence: `README.md`)
- Catalogue browser → HTTP API: requests catalogue (evidence: `README.md`)
- HTTP API → Input resolver: resolves input (evidence: `app/main.py`)
- Input resolver → YouTube client: looks up channel (evidence: `app/resolver.py`)
- Input resolver → SQLite catalogue: stores channel (evidence: `app/resolver.py`)
- Input resolver → Quota guard: charges lookup (evidence: `app/resolver.py`)
- YouTube client → YouTube Data API: requests metadata (evidence: `app/youtube.py`)
- HTTP API → Video streaming: starts stream (evidence: `app/main.py`)
- Video streaming → YouTube client: fetches pages (evidence: `app/streaming.py`)
- Video streaming → SQLite catalogue: reads and writes (evidence: `app/streaming.py`)
- Video streaming → Quota guard: checks and charges (evidence: `app/streaming.py`)
- Video streaming → Catalogue browser: streams SSE pages (evidence: `README.md`)
- HTTP API → SQLite catalogue: loads export data (evidence: `app/main.py`)
- HTTP API → YouTube client: enriches videos (evidence: `app/main.py`)
- HTTP API → Quota guard: guards enrichment (evidence: `app/main.py`)
- HTTP API → Export generator: generates export (evidence: `app/main.py`)
- Export generator → SQLite catalogue: streams stored rows (evidence: `app/exports.py`)
- HTTP API → Change detection: runs diff (evidence: `app/main.py`)
- Change detection → YouTube RSS feed: checks recent IDs (evidence: `app/diff.py`)
- Change detection → SQLite catalogue: reads and updates (evidence: `app/diff.py`)
- Change detection → YouTube client: refreshes catalogue (evidence: `app/diff.py`)
- Change detection → Quota guard: checks and charges (evidence: `app/diff.py`)
- HTTP API → Request limiter: configures middleware (evidence: `app/main.py`)
- Request limiter → Runtime settings: uses limits
- Quota guard → SQLite catalogue: records quota (evidence: `app/quota.py`)
- Quota guard → Runtime settings: reads budget (evidence: `app/quota.py`)
