# giorgibokuchava/youtube-automation architecture

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

- Interactive diagram: https://gitdiagram.com/giorgibokuchava/youtube-automation
- Repository: https://github.com/giorgibokuchava/youtube-automation

## Overview

Youtube-Automation turns Reddit and Instagram clips into long-form compilations or vertical Shorts, then prepares metadata and can upload the result to YouTube. The main entry point loads channel settings and dispatches to a pipeline; sourcing, clip processing, optional AI commentary, rendering, and publishing are distinct stages. The README documents thumbnail-only and AI-preview modes as additional capabilities. Some wiring is inferred only where the README establishes the product flow; unsampled implementation details are left out.

Main entry points: [`src/youtube_automation/pipeline.py`](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/pipeline.py) (Long-form pipeline), [`src/youtube_automation/app.py`](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/app.py) (CLI dispatcher), [`src/youtube_automation/shorts_pipeline.py`](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/shorts_pipeline.py) (Shorts pipeline), [`src/youtube_automation/sourcing.py`](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/sourcing.py) (Source coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and settings"]
  node_app["CLI dispatcher<br/>[app.py]"]
  node_config["Config loader<br/>[loader.py]"]
  node_pipeline["Long-form pipeline<br/>[pipeline.py]"]
  node_shorts_pipeline["Shorts pipeline<br/>[shorts_pipeline.py]"]
end

subgraph group_sourcing["Clip sourcing"]
  node_sourcing["Source coordinator<br/>[sourcing.py]"]
  node_reddit["Reddit client<br/>[client.py]"]
  node_instagram_scraper["Instagram scraper<br/>[scraper.py]"]
end

subgraph group_creation["Media creation"]
  node_video_processing["Clip processing"]
  node_commentary["Commentary generation<br/>[commentary.py]"]
  node_text_service["Text AI service<br/>[service.py]"]
  node_text_providers["Text AI providers"]
  node_voice["Voice synthesis<br/>[service.py]"]
  node_tts_providers["TTS providers"]
  node_media_render["Composition and media"]
  node_music["Background music<br/>[music.py]"]
end

subgraph group_publishing["Publishing"]
  node_metadata["Publishing metadata<br/>[metadata.py]"]
  node_ai_metadata["AI metadata<br/>[ai_metadata.py]"]
  node_thumbnail["Thumbnail sourcing<br/>[thumbnail.py]"]
  node_sessions[("Run history<br/>[sessions.py]")]
  node_upload["YouTube uploader<br/>[upload.py]"]
  node_preview["AI preview<br/>[preview.py]"]
end

node_user(("Operator"))
node_reddit_service{{"Reddit"}}
node_instagram_service{{"Instagram"}}
node_youtube{{"YouTube"}}
node_ffmpeg{{"FFmpeg"}}

node_user -->|"starts run"| node_app
node_app -->|"loads settings"| node_config
node_app -->|"dispatches"| node_pipeline
node_app -->|"dispatches"| node_shorts_pipeline
node_app -->|"dispatches preview"| node_preview
node_app -->|"sources thumbnail"| node_thumbnail
node_app -->|"sources videos"| node_sourcing
node_app -->|"saves session"| node_sessions
node_pipeline -->|"sources clips"| node_sourcing
node_shorts_pipeline -->|"sources clips"| node_sourcing
node_sourcing -->|"fetches posts"| node_reddit
node_reddit -->|"reads listings"| node_reddit_service
node_sourcing -->|"collects clips"| node_instagram_scraper
node_instagram_scraper -->|"fetches media"| node_instagram_service
node_pipeline -->|"processes clips"| node_video_processing
node_pipeline -->|"requests commentary"| node_commentary
node_commentary -->|"generates text"| node_text_service
node_text_service -->|"dispatches request"| node_text_providers
node_pipeline -->|"requests narration"| node_voice
node_voice -->|"dispatches synthesis"| node_tts_providers
node_pipeline -->|"renders compilation"| node_media_render
node_shorts_pipeline -->|"renders segments"| node_media_render
node_pipeline -->|"adds music"| node_music
node_shorts_pipeline -->|"adds music"| node_music
node_media_render -->|"runs media tools"| node_ffmpeg
node_pipeline -->|"prepares metadata"| node_metadata
node_shorts_pipeline -->|"prepares metadata"| node_metadata
node_pipeline -->|"requests AI metadata"| node_ai_metadata
node_shorts_pipeline -->|"requests AI metadata"| node_ai_metadata
node_ai_metadata -->|"generates metadata"| node_text_service
node_pipeline -->|"uploads result"| node_upload
node_shorts_pipeline -->|"uploads result"| node_upload
node_upload -->|"publishes video"| node_youtube
node_preview -->|"generates preview"| node_text_service
node_pipeline -->|"records run"| node_sessions
node_shorts_pipeline -->|"records run"| node_sessions

click node_app "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/app.py"
click node_config "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/config/loader.py"
click node_pipeline "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/pipeline.py"
click node_shorts_pipeline "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/shorts_pipeline.py"
click node_sourcing "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/sourcing.py"
click node_reddit "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/reddit/client.py"
click node_instagram_scraper "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/instagram/scraper.py"
click node_video_processing "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/media/video_processing.py"
click node_commentary "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/ai/text/commentary.py"
click node_text_service "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/ai/text/service.py"
click node_text_providers "https://github.com/giorgibokuchava/youtube-automation/tree/main/src/youtube_automation/ai/text/providers"
click node_voice "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/ai/tts/service.py"
click node_tts_providers "https://github.com/giorgibokuchava/youtube-automation/tree/main/src/youtube_automation/ai/tts/providers"
click node_media_render "https://github.com/giorgibokuchava/youtube-automation/tree/main/src/youtube_automation/media/composition"
click node_music "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/media/music.py"
click node_metadata "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/publishing/metadata.py"
click node_ai_metadata "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/publishing/ai_metadata.py"
click node_thumbnail "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/media/thumbnail.py"
click node_sessions "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/storage/sessions.py"
click node_upload "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/youtube/upload.py"
click node_preview "https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/ai/preview.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_app,node_config,node_pipeline,node_shorts_pipeline toneBlue
class node_sourcing,node_reddit,node_instagram_scraper toneAmber
class node_video_processing,node_commentary,node_text_service,node_text_providers,node_voice,node_tts_providers,node_media_render,node_music toneMint
class node_metadata,node_ai_metadata,node_thumbnail,node_sessions,node_upload,node_preview toneRose
class node_user,node_reddit_service,node_instagram_service,node_youtube,node_ffmpeg toneIndigo
```

## Components

### Entry and settings

- [CLI dispatcher](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/app.py): `src/youtube_automation/app.py`
- [Config loader](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/config/loader.py): `src/youtube_automation/config/loader.py`
- [Long-form pipeline](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/pipeline.py): `src/youtube_automation/pipeline.py`
- [Shorts pipeline](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/shorts_pipeline.py): `src/youtube_automation/shorts_pipeline.py`

### Clip sourcing

- [Source coordinator](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/sourcing.py): `src/youtube_automation/sourcing.py`
- [Reddit client](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/reddit/client.py): `src/youtube_automation/reddit/client.py`
- [Instagram scraper](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/instagram/scraper.py): `src/youtube_automation/instagram/scraper.py`

### Media creation

- [Clip processing](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/media/video_processing.py): `src/youtube_automation/media/video_processing.py`
- [Commentary generation](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/ai/text/commentary.py): `src/youtube_automation/ai/text/commentary.py`
- [Text AI service](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/ai/text/service.py): `src/youtube_automation/ai/text/service.py`
- [Text AI providers](https://github.com/giorgibokuchava/youtube-automation/tree/main/src/youtube_automation/ai/text/providers): `src/youtube_automation/ai/text/providers`
- [Voice synthesis](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/ai/tts/service.py): `src/youtube_automation/ai/tts/service.py`
- [TTS providers](https://github.com/giorgibokuchava/youtube-automation/tree/main/src/youtube_automation/ai/tts/providers): `src/youtube_automation/ai/tts/providers`
- [Composition and media](https://github.com/giorgibokuchava/youtube-automation/tree/main/src/youtube_automation/media/composition): `src/youtube_automation/media/composition`
- [Background music](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/media/music.py): `src/youtube_automation/media/music.py`

### Publishing

- [Publishing metadata](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/publishing/metadata.py): `src/youtube_automation/publishing/metadata.py`
- [AI metadata](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/publishing/ai_metadata.py): `src/youtube_automation/publishing/ai_metadata.py`
- [Thumbnail sourcing](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/media/thumbnail.py): `src/youtube_automation/media/thumbnail.py`
- [Run history](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/storage/sessions.py): `src/youtube_automation/storage/sessions.py`
- [YouTube uploader](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/youtube/upload.py): `src/youtube_automation/youtube/upload.py`
- [AI preview](https://github.com/giorgibokuchava/youtube-automation/blob/main/src/youtube_automation/ai/preview.py): `src/youtube_automation/ai/preview.py`

### Other components

- **Operator**
- **Reddit**
- **Instagram**
- **YouTube**
- **FFmpeg**

## Connections

- Operator → CLI dispatcher: starts run
- CLI dispatcher → Config loader: loads settings
- CLI dispatcher → Long-form pipeline: dispatches
- CLI dispatcher → Shorts pipeline: dispatches
- CLI dispatcher → AI preview: dispatches preview
- CLI dispatcher → Thumbnail sourcing: sources thumbnail
- CLI dispatcher → Source coordinator: sources videos
- CLI dispatcher → Run history: saves session
- Long-form pipeline → Source coordinator: sources clips
- Shorts pipeline → Source coordinator: sources clips
- Source coordinator → Reddit client: fetches posts
- Reddit client → Reddit: reads listings
- Source coordinator → Instagram scraper: collects clips
- Instagram scraper → Instagram: fetches media
- Long-form pipeline → Clip processing: processes clips
- Long-form pipeline → Commentary generation: requests commentary
- Commentary generation → Text AI service: generates text
- Text AI service → Text AI providers: dispatches request
- Long-form pipeline → Voice synthesis: requests narration
- Voice synthesis → TTS providers: dispatches synthesis
- Long-form pipeline → Composition and media: renders compilation
- Shorts pipeline → Composition and media: renders segments
- Long-form pipeline → Background music: adds music
- Shorts pipeline → Background music: adds music
- Composition and media → FFmpeg: runs media tools
- Long-form pipeline → Publishing metadata: prepares metadata
- Shorts pipeline → Publishing metadata: prepares metadata
- Long-form pipeline → AI metadata: requests AI metadata
- Shorts pipeline → AI metadata: requests AI metadata
- AI metadata → Text AI service: generates metadata
- Long-form pipeline → YouTube uploader: uploads result
- Shorts pipeline → YouTube uploader: uploads result
- YouTube uploader → YouTube: publishes video
- AI preview → Text AI service: generates preview
- Long-form pipeline → Run history: records run
- Shorts pipeline → Run history: records run