# batchping/teleflix architecture

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

- Interactive diagram: https://gitdiagram.com/batchping/teleflix
- Repository: https://github.com/batchping/teleflix

## Overview

TeleFlix turns a submitted video URL into an HLS catalog entry, then serves its segments through a Cloudflare Worker. The documented path runs from the dashboard through a GitHub Actions ingest runner, which segments and uploads to Telegram while recording metadata in D1. Playback uses signed URLs and an edge cache before fetching uncached segments from Telegram. The README also describes license checks, catalog management, and BYOI configuration; source excerpts were not available to verify internal call details, so these links reflect documented behavior.

Main entry points: [`worker/dist/index.js`](https://github.com/batchping/teleflix/blob/main/worker/dist/index.js) (Segment proxy), [`.github/workflows/ingest-video.yml`](https://github.com/batchping/teleflix/blob/main/.github/workflows/ingest-video.yml) (GitHub Actions runner), [`ingest/dist/index.js`](https://github.com/batchping/teleflix/blob/main/ingest/dist/index.js) (Ingest engine), [`worker/schema.sql`](https://github.com/batchping/teleflix/blob/main/worker/schema.sql) (D1 metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Video ingestion"]
  node_actions["GitHub Actions runner<br/>[ingest-video.yml]"]
  node_ingest_engine["Ingest engine<br/>[index.js]"]
  node_segmenter["HLS segmentation<br/>[index.js]"]
  node_upload_limiter["Upload rate limiter<br/>[index.js]"]
end

subgraph group_worker["Edge playback"]
  node_worker_api["Worker API<br/>[index.js]"]
  node_license{{"License validation<br/>[core.wasm]"}}
  node_playback_signing["Playback signing<br/>[index.js]"]
  node_stream_proxy["Segment proxy<br/>[index.js]"]
  node_edge_cache[("Cloudflare edge cache")]
end

subgraph group_data["Metadata and storage"]
  node_catalog_db[("D1 metadata<br/>[schema.sql]")]
  node_telegram[("Telegram channels")]
end

subgraph group_client["User experience"]
  node_dashboard["TeleFlix dashboard"]
  node_player["HLS.js player"]
end

node_operator(("Video operator"))
node_video_source["Remote video URL"]
node_github_dispatch["GitHub workflow dispatch"]

node_operator -->|"submits URL"| node_dashboard
node_dashboard -->|"dispatches job"| node_github_dispatch
node_github_dispatch -->|"starts workflow"| node_actions
node_actions -->|"runs"| node_ingest_engine
node_ingest_engine -->|"downloads video"| node_video_source
node_ingest_engine -->|"segments video"| node_segmenter
node_segmenter -->|"limits uploads"| node_upload_limiter
node_upload_limiter -->|"uploads segments"| node_telegram
node_actions -->|"records metadata"| node_catalog_db
node_dashboard -->|"tests and configures"| node_worker_api
node_dashboard -->|"requests playback"| node_worker_api
node_worker_api -->|"validates license"| node_license
node_worker_api -->|"reads catalog"| node_catalog_db
node_worker_api -->|"signs URLs"| node_playback_signing
node_player -->|"requests segments"| node_stream_proxy
node_stream_proxy -->|"checks cache"| node_edge_cache
node_stream_proxy -->|"fetches misses"| node_telegram
node_stream_proxy -->|"caches segments"| node_edge_cache
node_stream_proxy -->|"streams segments"| node_player

click node_actions "https://github.com/batchping/teleflix/blob/main/.github/workflows/ingest-video.yml"
click node_ingest_engine "https://github.com/batchping/teleflix/blob/main/ingest/dist/index.js"
click node_segmenter "https://github.com/batchping/teleflix/blob/main/ingest/dist/index.js"
click node_upload_limiter "https://github.com/batchping/teleflix/blob/main/ingest/dist/index.js"
click node_worker_api "https://github.com/batchping/teleflix/blob/main/worker/dist/index.js"
click node_license "https://github.com/batchping/teleflix/blob/main/worker/dist/core.wasm"
click node_playback_signing "https://github.com/batchping/teleflix/blob/main/worker/dist/index.js"
click node_stream_proxy "https://github.com/batchping/teleflix/blob/main/worker/dist/index.js"
click node_catalog_db "https://github.com/batchping/teleflix/blob/main/worker/schema.sql"

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_actions,node_ingest_engine,node_segmenter,node_upload_limiter toneBlue
class node_worker_api,node_license,node_playback_signing,node_stream_proxy,node_edge_cache toneAmber
class node_catalog_db,node_telegram toneMint
class node_dashboard,node_player toneRose
class node_operator,node_video_source,node_github_dispatch toneIndigo
```

## Components

### Video ingestion

- [GitHub Actions runner](https://github.com/batchping/teleflix/blob/main/.github/workflows/ingest-video.yml): `.github/workflows/ingest-video.yml`
- [Ingest engine](https://github.com/batchping/teleflix/blob/main/ingest/dist/index.js): `ingest/dist/index.js`
- [HLS segmentation](https://github.com/batchping/teleflix/blob/main/ingest/dist/index.js): `ingest/dist/index.js`
- [Upload rate limiter](https://github.com/batchping/teleflix/blob/main/ingest/dist/index.js): `ingest/dist/index.js`

### Edge playback

- [Worker API](https://github.com/batchping/teleflix/blob/main/worker/dist/index.js): `worker/dist/index.js`
- [License validation](https://github.com/batchping/teleflix/blob/main/worker/dist/core.wasm): `worker/dist/core.wasm`
- [Playback signing](https://github.com/batchping/teleflix/blob/main/worker/dist/index.js): `worker/dist/index.js`
- [Segment proxy](https://github.com/batchping/teleflix/blob/main/worker/dist/index.js): `worker/dist/index.js`
- **Cloudflare edge cache**

### Metadata and storage

- [D1 metadata](https://github.com/batchping/teleflix/blob/main/worker/schema.sql): `worker/schema.sql`
- **Telegram channels**

### User experience

- **TeleFlix dashboard**
- **HLS.js player**

### Other components

- **Video operator**
- **Remote video URL**
- **GitHub workflow dispatch**

## Connections

- Video operator → TeleFlix dashboard: submits URL (evidence: `README.md`)
- TeleFlix dashboard → GitHub workflow dispatch: dispatches job (evidence: `README.md`)
- GitHub workflow dispatch → GitHub Actions runner: starts workflow (evidence: `README.md`)
- GitHub Actions runner → Ingest engine: runs (evidence: `README.md`)
- Ingest engine → Remote video URL: downloads video (evidence: `README.md`)
- Ingest engine → HLS segmentation: segments video (evidence: `README.md`)
- HLS segmentation → Upload rate limiter: limits uploads (evidence: `README.md`)
- Upload rate limiter → Telegram channels: uploads segments (evidence: `README.md`)
- GitHub Actions runner → D1 metadata: records metadata (evidence: `README.md`)
- TeleFlix dashboard → Worker API: tests and configures (evidence: `README.md`)
- TeleFlix dashboard → Worker API: requests playback (evidence: `README.md`)
- Worker API → License validation: validates license (evidence: `README.md`)
- Worker API → D1 metadata: reads catalog (evidence: `README.md`)
- Worker API → Playback signing: signs URLs (evidence: `README.md`)
- HLS.js player → Segment proxy: requests segments (evidence: `README.md`)
- Segment proxy → Cloudflare edge cache: checks cache (evidence: `README.md`)
- Segment proxy → Telegram channels: fetches misses (evidence: `README.md`)
- Segment proxy → Cloudflare edge cache: caches segments (evidence: `README.md`)
- Segment proxy → HLS.js player: streams segments (evidence: `README.md`)