# horatiumol/youtube-agents architecture

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

- Interactive diagram: https://gitdiagram.com/horatiumol/youtube-agents
- Repository: https://github.com/horatiumol/youtube-agents

## Overview

This repository supports a YouTube content-production workflow: a user uploads a Word brief to a watched Drive folder; the watcher extracts its text and invokes Claude Code, which is prompted to run research, scriptwriting, title/description, and thumbnail stages and save three versioned outputs. The watcher and its orchestration are excerpted; the skill files, context documents, and agent definitions are present in the tree but unsampled, so their internal behavior is not inferred. Edges between stages reflect the explicit sequence in the watcher’s prompt.

Main entry points: [`watch_drive_folder.py`](https://github.com/horatiumol/youtube-agents/blob/main/watch_drive_folder.py) (Drive watcher), [`skills/trend-research.md`](https://github.com/horatiumol/youtube-agents/blob/main/skills/trend-research.md) (Trend research), [`skills/script-writer.md`](https://github.com/horatiumol/youtube-agents/blob/main/skills/script-writer.md) (Script writing), [`skills/title-generator.md`](https://github.com/horatiumol/youtube-agents/blob/main/skills/title-generator.md) (Title generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Brief intake"]
  node_drive_brief[("Drive brief folder")]
  node_watcher["Drive watcher"]
  node_brief_text["Extracted brief"]
end

subgraph group_production["Content production"]
  node_claude["Claude Code"]
  node_research["Trend research<br/>[trend-research.md]"]
  node_script["Script writing<br/>[script-writer.md]"]
  node_titles["Title generation<br/>[title-generator.md]"]
  node_thumbnail["Thumbnail concepts"]
end

subgraph group_context["Brand context"]
  node_audience["Audience context<br/>[audience.md]"]
  node_top_videos["Top video references<br/>[top-videos.md]"]
  node_brand_voice["Brand voice<br/>[brand-voice.md]"]
end

subgraph group_deliverables["Video deliverables"]
  node_script_output["Generated scripts"]
  node_title_output["Titles and descriptions"]
  node_thumbnail_output["Thumbnail prompts"]
end

node_creator(("Content creator"))

node_creator -->|"uploads brief"| node_drive_brief
node_drive_brief -->|"triggers on .docx"| node_watcher
node_watcher -->|"extracts text"| node_brief_text
node_watcher -->|"invokes with prompt"| node_claude
node_claude -->|"runs first"| node_research
node_research -->|"then drafts"| node_script
node_script -->|"then generates"| node_titles
node_titles -->|"then designs"| node_thumbnail
node_claude -->|"uses context"| node_audience
node_claude -->|"uses context"| node_top_videos
node_claude -->|"uses context"| node_brand_voice
node_claude -->|"writes script"| node_script_output
node_claude -->|"writes titles"| node_title_output
node_claude -->|"writes prompts"| node_thumbnail_output

click node_watcher "https://github.com/horatiumol/youtube-agents/blob/main/watch_drive_folder.py"
click node_brief_text "https://github.com/horatiumol/youtube-agents/blob/main/watch_drive_folder.py"
click node_research "https://github.com/horatiumol/youtube-agents/blob/main/skills/trend-research.md"
click node_script "https://github.com/horatiumol/youtube-agents/blob/main/skills/script-writer.md"
click node_titles "https://github.com/horatiumol/youtube-agents/blob/main/skills/title-generator.md"
click node_thumbnail "https://github.com/horatiumol/youtube-agents/blob/main/skills/thumbnail-creator.md"
click node_audience "https://github.com/horatiumol/youtube-agents/blob/main/contexto/audience.md"
click node_top_videos "https://github.com/horatiumol/youtube-agents/blob/main/contexto/top-videos.md"
click node_brand_voice "https://github.com/horatiumol/youtube-agents/blob/main/contexto/brand-voice.md"
click node_script_output "https://github.com/horatiumol/youtube-agents/tree/main/outputs/guiones"
click node_title_output "https://github.com/horatiumol/youtube-agents/tree/main/outputs/titulos"
click node_thumbnail_output "https://github.com/horatiumol/youtube-agents/tree/main/outputs/miniaturas"

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_drive_brief,node_watcher,node_brief_text toneBlue
class node_claude,node_research,node_script,node_titles,node_thumbnail toneAmber
class node_audience,node_top_videos,node_brand_voice toneMint
class node_script_output,node_title_output,node_thumbnail_output toneRose
class node_creator toneIndigo
```

## Components

### Brief intake

- **Drive brief folder**
- [Drive watcher](https://github.com/horatiumol/youtube-agents/blob/main/watch_drive_folder.py): `watch_drive_folder.py`
- [Extracted brief](https://github.com/horatiumol/youtube-agents/blob/main/watch_drive_folder.py): `watch_drive_folder.py`

### Content production

- **Claude Code**
- [Trend research](https://github.com/horatiumol/youtube-agents/blob/main/skills/trend-research.md): `skills/trend-research.md`
- [Script writing](https://github.com/horatiumol/youtube-agents/blob/main/skills/script-writer.md): `skills/script-writer.md`
- [Title generation](https://github.com/horatiumol/youtube-agents/blob/main/skills/title-generator.md): `skills/title-generator.md`
- [Thumbnail concepts](https://github.com/horatiumol/youtube-agents/blob/main/skills/thumbnail-creator.md): `skills/thumbnail-creator.md`

### Brand context

- [Audience context](https://github.com/horatiumol/youtube-agents/blob/main/contexto/audience.md): `contexto/audience.md`
- [Top video references](https://github.com/horatiumol/youtube-agents/blob/main/contexto/top-videos.md): `contexto/top-videos.md`
- [Brand voice](https://github.com/horatiumol/youtube-agents/blob/main/contexto/brand-voice.md): `contexto/brand-voice.md`

### Video deliverables

- [Generated scripts](https://github.com/horatiumol/youtube-agents/tree/main/outputs/guiones): `outputs/guiones`
- [Titles and descriptions](https://github.com/horatiumol/youtube-agents/tree/main/outputs/titulos): `outputs/titulos`
- [Thumbnail prompts](https://github.com/horatiumol/youtube-agents/tree/main/outputs/miniaturas): `outputs/miniaturas`

### Other components

- **Content creator**

## Connections

- Content creator → Drive brief folder: uploads brief
- Drive brief folder → Drive watcher: triggers on .docx (evidence: `watch_drive_folder.py`)
- Drive watcher → Extracted brief: extracts text (evidence: `watch_drive_folder.py`)
- Drive watcher → Claude Code: invokes with prompt (evidence: `watch_drive_folder.py`)
- Claude Code → Trend research: runs first
- Trend research → Script writing: then drafts
- Script writing → Title generation: then generates
- Title generation → Thumbnail concepts: then designs
- Claude Code → Audience context: uses context
- Claude Code → Top video references: uses context
- Claude Code → Brand voice: uses context
- Claude Code → Generated scripts: writes script
- Claude Code → Titles and descriptions: writes titles
- Claude Code → Thumbnail prompts: writes prompts
