# therr-ctrl/video-scout-pipeline architecture

> Architecture diagram of the GitHub repository therr-ctrl/video-scout-pipeline, 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/therr-ctrl/video-scout-pipeline
- Repository: https://github.com/therr-ctrl/video-scout-pipeline

## Overview

Video Scout Pipeline turns public Reddit stories and YouTube anecdotes into narrated videos, then uploads them privately for a manual review window. Its main workflow is scout → candidate queue → Gemini-assisted scripting → local rendering → quality-gated YouTube upload; the panel can also initiate work. The repository includes a separate canal2 planning and video-generation pipeline. Core workflow links are documented in the README; some canal2 render dependencies are supported by the source index, so unsampled behavior is not expanded.

Main entry points: [`pipeline.py`](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/pipeline.py) (Pipeline runner), [`generar_video_maestro.py`](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/generar_video_maestro.py) (Video renderer), [`script_writer.py`](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/script_writer.py) (Script writer), [`cola.py`](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/cola.py) (Candidate queue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scouting["Story discovery"]
  node_reddit_scout["Reddit scout<br/>[trend_scout.py]"]
  node_yt_scout["YouTube scout<br/>[youtube_scout.py]"]
end

subgraph group_writing["Queue and scripts"]
  node_candidate_queue[("Candidate queue<br/>[cola.py]")]
  node_script_writer["Script writer<br/>[script_writer.py]"]
  node_gemini["Gemini client<br/>[gemini.py]"]
  node_script_store["Story scripts<br/>[script_writer.py]"]
  node_long_splitter["Long-story splitter"]
  node_canal2_planner["Content planner<br/>[content_planner.py]"]
  node_canal2_writer["Canal2 script writer<br/>[script_writer.py]"]
end

subgraph group_production["Video production"]
  node_renderer["Video renderer"]
  node_narrator["Narration<br/>[narrador.py]"]
  node_broll["Background footage"]
  node_video_store["Rendered videos"]
  node_canal2_renderer["Canal2 renderer"]
end

subgraph group_operations["Review and operations"]
  node_pipeline["Pipeline runner<br/>[pipeline.py]"]
  node_panel["Local review panel<br/>[servidor.py]"]
  node_publisher["YouTube publisher<br/>[publisher.py]"]
  node_canal2_publisher["Canal2 publisher<br/>[publisher.py]"]
  node_state_store[("JSON state<br/>[almacen.py]")]
end

node_owner(("Channel owner"))
node_reddit(("Reddit RSS"))
node_yt_source(("YouTube sources"))
node_youtube(("YouTube"))

node_reddit -->|"provides feeds"| node_reddit_scout
node_reddit_scout -->|"adds candidates"| node_candidate_queue
node_yt_source -->|"provides captions"| node_yt_scout
node_yt_scout -->|"adds candidates"| node_candidate_queue
node_candidate_queue -->|"supplies candidates"| node_script_writer
node_script_writer -->|"rewrites stories"| node_gemini
node_script_writer -->|"writes scripts"| node_script_store
node_script_writer -->|"splits stories"| node_long_splitter
node_script_store -->|"provides narration text"| node_renderer
node_renderer -->|"generates speech"| node_narrator
node_renderer -->|"requests footage"| node_broll
node_renderer -->|"writes videos"| node_video_store
node_pipeline -->|"runs stage"| node_reddit_scout
node_pipeline -->|"runs stage"| node_yt_scout
node_pipeline -->|"runs stage"| node_script_writer
node_pipeline -->|"runs stage"| node_renderer
node_pipeline -->|"runs stage"| node_publisher
node_video_store -->|"supplies video"| node_publisher
node_publisher -->|"checks metadata"| node_gemini
node_publisher -->|"uploads privately"| node_youtube
node_owner -->|"reviews and controls"| node_panel
node_panel -->|"can start render"| node_renderer
node_candidate_queue -->|"persists queue state"| node_state_store
node_pipeline -->|"runs second pipeline"| node_canal2_planner
node_canal2_planner -.->|"plans then writes"| node_canal2_writer
node_canal2_writer -->|"uses model"| node_gemini
node_canal2_writer -.->|"supplies planned scripts"| node_canal2_renderer
node_canal2_renderer -.->|"produces for publishing"| node_canal2_publisher
node_canal2_renderer -->|"uses b-roll module"| node_broll
node_canal2_publisher -->|"checks metadata"| node_gemini

click node_reddit_scout "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/trend_scout.py"
click node_yt_scout "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/youtube_scout.py"
click node_candidate_queue "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/cola.py"
click node_script_writer "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/script_writer.py"
click node_gemini "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/gemini.py"
click node_script_store "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/script_writer.py"
click node_long_splitter "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/partir_historias.py"
click node_renderer "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/generar_video_maestro.py"
click node_narrator "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/narrador.py"
click node_broll "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/hyperframes_broll.py"
click node_video_store "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/generar_video_maestro.py"
click node_pipeline "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/pipeline.py"
click node_panel "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/servidor.py"
click node_publisher "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/publisher.py"
click node_canal2_planner "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/canal2/content_planner.py"
click node_canal2_writer "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/canal2/script_writer.py"
click node_canal2_renderer "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/canal2/generar_video_maestro.py"
click node_canal2_publisher "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/canal2/publisher.py"
click node_state_store "https://github.com/therr-ctrl/video-scout-pipeline/blob/main/almacen.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_reddit_scout,node_yt_scout toneBlue
class node_candidate_queue,node_script_writer,node_gemini,node_script_store,node_long_splitter,node_canal2_planner,node_canal2_writer toneAmber
class node_renderer,node_narrator,node_broll,node_video_store,node_canal2_renderer toneMint
class node_pipeline,node_panel,node_publisher,node_canal2_publisher,node_state_store toneRose
class node_owner,node_reddit,node_yt_source,node_youtube toneIndigo
```

## Components

### Story discovery

- [Reddit scout](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/trend_scout.py): `trend_scout.py`
- [YouTube scout](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/youtube_scout.py): `youtube_scout.py`

### Queue and scripts

- [Candidate queue](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/cola.py): `cola.py`
- [Script writer](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/script_writer.py): `script_writer.py`
- [Gemini client](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/gemini.py): `gemini.py`
- [Story scripts](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/script_writer.py): `script_writer.py`
- [Long-story splitter](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/partir_historias.py): `partir_historias.py`
- [Content planner](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/canal2/content_planner.py): `canal2/content_planner.py`
- [Canal2 script writer](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/canal2/script_writer.py): `canal2/script_writer.py`

### Video production

- [Video renderer](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/generar_video_maestro.py): `generar_video_maestro.py`
- [Narration](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/narrador.py): `narrador.py`
- [Background footage](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/hyperframes_broll.py): `hyperframes_broll.py`
- [Rendered videos](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/generar_video_maestro.py): `generar_video_maestro.py`
- [Canal2 renderer](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/canal2/generar_video_maestro.py): `canal2/generar_video_maestro.py`

### Review and operations

- [Pipeline runner](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/pipeline.py): `pipeline.py`
- [Local review panel](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/servidor.py): `servidor.py`
- [YouTube publisher](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/publisher.py): `publisher.py`
- [Canal2 publisher](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/canal2/publisher.py): `canal2/publisher.py`
- [JSON state](https://github.com/therr-ctrl/video-scout-pipeline/blob/main/almacen.py): `almacen.py`

### Other components

- **Channel owner**
- **Reddit RSS**
- **YouTube sources**
- **YouTube**

## Connections

- Reddit RSS → Reddit scout: provides feeds
- Reddit scout → Candidate queue: adds candidates (evidence: `trend_scout.py`)
- YouTube sources → YouTube scout: provides captions
- YouTube scout → Candidate queue: adds candidates (evidence: `youtube_scout.py`)
- Candidate queue → Script writer: supplies candidates (evidence: `script_writer.py`)
- Script writer → Gemini client: rewrites stories (evidence: `script_writer.py`)
- Script writer → Story scripts: writes scripts (evidence: `script_writer.py`)
- Script writer → Long-story splitter: splits stories (evidence: `script_writer.py`)
- Story scripts → Video renderer: provides narration text (evidence: `script_writer.py`)
- Video renderer → Narration: generates speech (evidence: `generar_video_maestro.py`)
- Video renderer → Background footage: requests footage (evidence: `generar_video_maestro.py`)
- Video renderer → Rendered videos: writes videos (evidence: `generar_video_maestro.py`)
- Pipeline runner → Reddit scout: runs stage (evidence: `pipeline.py`)
- Pipeline runner → YouTube scout: runs stage (evidence: `pipeline.py`)
- Pipeline runner → Script writer: runs stage (evidence: `pipeline.py`)
- Pipeline runner → Video renderer: runs stage (evidence: `pipeline.py`)
- Pipeline runner → YouTube publisher: runs stage (evidence: `pipeline.py`)
- Rendered videos → YouTube publisher: supplies video
- YouTube publisher → Gemini client: checks metadata (evidence: `publisher.py`)
- YouTube publisher → YouTube: uploads privately
- Channel owner → Local review panel: reviews and controls (evidence: `servidor.py`)
- Local review panel → Video renderer: can start render (evidence: `servidor.py`)
- Candidate queue → JSON state: persists queue state (evidence: `cola.py`)
- Pipeline runner → Content planner: runs second pipeline
- Content planner → Canal2 script writer: plans then writes
- Canal2 script writer → Gemini client: uses model (evidence: `canal2/script_writer.py`)
- Canal2 script writer → Canal2 renderer: supplies planned scripts
- Canal2 renderer → Canal2 publisher: produces for publishing
- Canal2 renderer → Background footage: uses b-roll module (evidence: `canal2/generar_video_maestro.py`)
- Canal2 publisher → Gemini client: checks metadata (evidence: `canal2/publisher.py`)
