# furqanraza4343/yt_clipping_automation architecture

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

- Interactive diagram: https://gitdiagram.com/furqanraza4343/yt_clipping_automation
- Repository: https://github.com/furqanraza4343/yt_clipping_automation

## Overview

ShortsPilot automates turning configured videos, YouTube channels, or watch folders into reviewed and scheduled Shorts. Its worker coordinates discovery, OpenShorts processing, deterministic safety and quality checks, metadata generation, scheduling, and YouTube publication; SQLite records resumable state. Operators manage sources, approvals, integrations, and health through the dashboard or commands. The README documents the principal workflow and optional Drive and Telegram capabilities; sampled excerpts do not expose every internal call, so some subsystem links are documented at workflow level.

Main entry points: [`shortspilot/supervisor.py`](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/supervisor.py) (Pipeline supervisor), [`shortspilot/web/app.py`](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/web/app.py) (Dashboard), [`shortspilot/discovery.py`](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/discovery.py) (Video discovery), [`shortspilot/engine_client.py`](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/engine_client.py) (Engine client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Clip workflow"]
  node_sources["Sources and channels<br/>[sources.py]"]
  node_discovery["Video discovery<br/>[discovery.py]"]
  node_engineclient["Engine client<br/>[engine_client.py]"]
  node_openshorts["OpenShorts engine"]
  node_media["Media checks<br/>[media.py]"]
  node_polish["Clip polishing<br/>[polish.py]"]
  node_gates["Safety and gates<br/>[gates.py]"]
  node_metadata["Metadata generation<br/>[metadata.py]"]
  node_scheduler["Slot scheduler<br/>[scheduler.py]"]
  node_windows["Source windows<br/>[windows.py]"]
end

subgraph group_core["Worker and state"]
  node_worker["Pipeline supervisor<br/>[supervisor.py]"]
  node_state[("SQLite state<br/>[db.py]")]
  node_config["Runtime settings<br/>[config.py]"]
  node_cookies["YouTube cookies<br/>[cookies.py]"]
end

subgraph group_delivery["Publishing integrations"]
  node_llm["DeepSeek client<br/>[llm.py]"]
  node_youtube["YouTube publishing<br/>[youtube.py]"]
  node_drive["Drive delivery<br/>[drive.py]"]
  node_telegram["Telegram controls<br/>[notify.py]"]
end

subgraph group_operator["Operator controls"]
  node_dashboard["Dashboard<br/>[app.py]"]
  node_auth["Dashboard auth<br/>[auth.py]"]
end

node_operator(("Operator"))

node_operator -->|"manages"| node_dashboard
node_dashboard -->|"authenticates with"| node_auth
node_dashboard -->|"queues commands"| node_worker
node_worker -->|"loads policy"| node_sources
node_worker -->|"discovers videos"| node_discovery
node_worker -->|"submits jobs"| node_engineclient
node_engineclient -->|"calls API"| node_openshorts
node_openshorts -->|"returns clips"| node_worker
node_worker -->|"checks clips"| node_media
node_worker -->|"processes clips"| node_polish
node_worker -->|"evaluates clips"| node_gates
node_worker -->|"requests metadata"| node_metadata
node_metadata -->|"generates text"| node_llm
node_worker -->|"assigns slots"| node_scheduler
node_worker -->|"uploads and verifies"| node_youtube
node_worker -.->|"delivers clips"| node_drive
node_worker -.->|"sends alerts"| node_telegram
node_worker -->|"updates state"| node_state
node_dashboard -->|"reads state"| node_state
node_worker -->|"uses settings"| node_config
node_discovery -->|"uses cookies"| node_cookies
node_worker -.->|"splits long sources"| node_windows

click node_dashboard "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/web/app.py"
click node_auth "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/auth.py"
click node_sources "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/sources.py"
click node_worker "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/supervisor.py"
click node_discovery "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/discovery.py"
click node_engineclient "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/engine_client.py"
click node_media "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/media.py"
click node_polish "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/polish.py"
click node_gates "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/gates.py"
click node_metadata "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/metadata.py"
click node_llm "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/llm.py"
click node_scheduler "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/scheduler.py"
click node_youtube "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/youtube.py"
click node_drive "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/drive.py"
click node_telegram "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/notify.py"
click node_state "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/db.py"
click node_config "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/config.py"
click node_cookies "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/cookies.py"
click node_windows "https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/windows.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_sources,node_discovery,node_engineclient,node_openshorts,node_media,node_polish,node_gates,node_metadata,node_scheduler,node_windows toneBlue
class node_worker,node_state,node_config,node_cookies toneAmber
class node_llm,node_youtube,node_drive,node_telegram toneMint
class node_dashboard,node_auth toneRose
class node_operator toneIndigo
```

## Components

### Clip workflow

- [Sources and channels](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/sources.py): `shortspilot/sources.py`
- [Video discovery](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/discovery.py): `shortspilot/discovery.py`
- [Engine client](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/engine_client.py): `shortspilot/engine_client.py`
- **OpenShorts engine**
- [Media checks](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/media.py): `shortspilot/media.py`
- [Clip polishing](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/polish.py): `shortspilot/polish.py`
- [Safety and gates](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/gates.py): `shortspilot/gates.py`
- [Metadata generation](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/metadata.py): `shortspilot/metadata.py`
- [Slot scheduler](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/scheduler.py): `shortspilot/scheduler.py`
- [Source windows](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/windows.py): `shortspilot/windows.py`

### Worker and state

- [Pipeline supervisor](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/supervisor.py): `shortspilot/supervisor.py`
- [SQLite state](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/db.py): `shortspilot/db.py`
- [Runtime settings](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/config.py): `shortspilot/config.py`
- [YouTube cookies](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/cookies.py): `shortspilot/cookies.py`

### Publishing integrations

- [DeepSeek client](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/llm.py): `shortspilot/llm.py`
- [YouTube publishing](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/youtube.py): `shortspilot/youtube.py`
- [Drive delivery](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/drive.py): `shortspilot/drive.py`
- [Telegram controls](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/notify.py): `shortspilot/notify.py`

### Operator controls

- [Dashboard](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/web/app.py): `shortspilot/web/app.py`
- [Dashboard auth](https://github.com/furqanraza4343/yt_clipping_automation/blob/main/shortspilot/auth.py): `shortspilot/auth.py`

### Other components

- **Operator**

## Connections

- Operator → Dashboard: manages (evidence: `README.md`)
- Dashboard → Dashboard auth: authenticates with (evidence: `shortspilot/web/app.py`)
- Dashboard → Pipeline supervisor: queues commands (evidence: `shortspilot/web/app.py`)
- Pipeline supervisor → Sources and channels: loads policy (evidence: `shortspilot/supervisor.py`)
- Pipeline supervisor → Video discovery: discovers videos (evidence: `README.md`)
- Pipeline supervisor → Engine client: submits jobs (evidence: `README.md`)
- Engine client → OpenShorts engine: calls API (evidence: `shortspilot/engine_client.py`)
- OpenShorts engine → Pipeline supervisor: returns clips (evidence: `README.md`)
- Pipeline supervisor → Media checks: checks clips (evidence: `shortspilot/supervisor.py`)
- Pipeline supervisor → Clip polishing: processes clips (evidence: `shortspilot/supervisor.py`)
- Pipeline supervisor → Safety and gates: evaluates clips (evidence: `README.md`)
- Pipeline supervisor → Metadata generation: requests metadata (evidence: `README.md`)
- Metadata generation → DeepSeek client: generates text (evidence: `shortspilot/metadata.py`)
- Pipeline supervisor → Slot scheduler: assigns slots (evidence: `shortspilot/supervisor.py`)
- Pipeline supervisor → YouTube publishing: uploads and verifies (evidence: `README.md`)
- Pipeline supervisor → Drive delivery: delivers clips (evidence: `README.md`)
- Pipeline supervisor → Telegram controls: sends alerts (evidence: `README.md`)
- Pipeline supervisor → SQLite state: updates state (evidence: `shortspilot/supervisor.py`)
- Dashboard → SQLite state: reads state (evidence: `shortspilot/web/app.py`)
- Pipeline supervisor → Runtime settings: uses settings (evidence: `shortspilot/runtime.py`)
- Video discovery → YouTube cookies: uses cookies (evidence: `shortspilot/discovery.py`)
- Pipeline supervisor → Source windows: splits long sources (evidence: `README.md`)
