# bhancockio/adk-youtube-thumbnail-agent architecture

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

- Interactive diagram: https://gitdiagram.com/bhancockio/adk-youtube-thumbnail-agent
- Repository: https://github.com/bhancockio/adk-youtube-thumbnail-agent

## Overview

This is an ADK multi-agent YouTube thumbnail style-cloning and generation application. The root agent coordinates channel collection, reference-thumbnail analysis, style synthesis, prompt creation, and image generation; users can also request revisions that use the prior generated image. The graph includes README-documented stages and tree-supported analyzer components, but some internal analyzer wiring and callback registration are not shown in the sampled source, so uncertain connections are omitted.

Main entry points: [`youtube_thumbnail_agent/agent.py`](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/agent.py) (Thumbnail Manager), [`youtube_thumbnail_agent/sub_agents/thumbnail_scraper/tools/scrape_channel.py`](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_scraper/tools/scrape_channel.py) (Scrape Channel), [`youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/analysis_process_agent.py`](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/analysis_process_agent.py) (Analysis Process), [`youtube_thumbnail_agent/sub_agents/generate_image_agent/tools/create_image.py`](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/generate_image_agent/tools/create_image.py) (Create or Edit Image)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_coordination["Workflow Coordination"]
  node_root_agent["Thumbnail Manager<br/>[agent.py]"]
end

subgraph group_reference["Reference Analysis"]
  node_scraper_agent["Channel Scraper<br/>[agent.py]"]
  node_scrape_tool["Scrape Channel<br/>[scrape_channel.py]"]
  node_reference_images[("Reference Images<br/>[constants.py]")]
  node_analyzer_agent["Thumbnail Analyzer<br/>[agent.py]"]
  node_analysis_loop["Analysis Loop<br/>[agent.py]"]
  node_analysis_process["Analysis Process"]
  node_selector["Thumbnail Selector"]
  node_single_analyzer["Single Thumbnail Analysis"]
  node_analyze_tool["Load Thumbnail"]
  node_analysis_save["Save Analysis"]
  node_save_tool["Analysis Storage Tool<br/>[save_analysis.py]"]
  node_style_guide["Style Guide"]
end

subgraph group_prompting["Prompt Design"]
  node_prompt_agent["Prompt Generator<br/>[agent.py]"]
end

subgraph group_generation["Image Generation"]
  node_asset_callback["User Image Callback<br/>[callbacks.py]"]
  node_assets[("User Assets<br/>[constants.py]")]
  node_image_agent["Image Generator<br/>[agent.py]"]
  node_create_image["Create or Edit Image<br/>[create_image.py]"]
  node_generated_images[("Generated Thumbnails<br/>[constants.py]")]
end

node_creator(("Creator"))
node_youtube["YouTube Data API"]
node_openai["OpenAI Image API"]

node_creator -->|"provides requests"| node_root_agent
node_root_agent -->|"asks for details"| node_creator
node_root_agent -->|"delegates collection"| node_scraper_agent
node_scraper_agent -->|"invokes"| node_scrape_tool
node_scrape_tool -->|"queries channel"| node_youtube
node_scrape_tool -->|"downloads thumbnails"| node_youtube
node_scrape_tool -->|"writes thumbnails"| node_reference_images
node_root_agent -->|"delegates analysis"| node_analyzer_agent
node_analyzer_agent -->|"runs iteratively"| node_analysis_loop
node_analysis_loop -->|"repeats"| node_analysis_process
node_analysis_process -->|"selects thumbnail"| node_selector
node_analysis_process -->|"runs analysis"| node_single_analyzer
node_single_analyzer -->|"loads image"| node_analyze_tool
node_analyze_tool -->|"reads thumbnail"| node_reference_images
node_analysis_process -->|"saves result"| node_analysis_save
node_analysis_save -->|"uses tool"| node_save_tool
node_analyzer_agent -->|"synthesizes analyses"| node_style_guide
node_root_agent -->|"delegates prompting"| node_prompt_agent
node_prompt_agent -->|"collects video details"| node_creator
node_root_agent -->|"delegates generation"| node_image_agent
node_image_agent -->|"invokes"| node_create_image
node_asset_callback -->|"saves uploaded images"| node_assets
node_create_image -->|"reads references"| node_assets
node_create_image -->|"generates or edits"| node_openai
node_create_image -->|"saves output"| node_generated_images
node_root_agent -->|"presents result"| node_creator

click node_root_agent "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/agent.py"
click node_scraper_agent "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_scraper/agent.py"
click node_scrape_tool "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_scraper/tools/scrape_channel.py"
click node_reference_images "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/constants.py"
click node_analyzer_agent "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/agent.py"
click node_analysis_loop "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/agent.py"
click node_analysis_process "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/analysis_process_agent.py"
click node_selector "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/thumbnail_selector_agent.py"
click node_single_analyzer "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/single_thumbnail_analyzer_agent.py"
click node_analyze_tool "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/tools/analyze_thumbnail.py"
click node_analysis_save "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/save_analysis_agent.py"
click node_save_tool "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/tools/save_analysis.py"
click node_style_guide "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/style_guide_generator_agent.py"
click node_prompt_agent "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/prompt_generator/agent.py"
click node_asset_callback "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/shared_lib/callbacks.py"
click node_assets "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/constants.py"
click node_image_agent "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/generate_image_agent/agent.py"
click node_create_image "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/generate_image_agent/tools/create_image.py"
click node_generated_images "https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/constants.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_root_agent toneBlue
class node_scraper_agent,node_scrape_tool,node_reference_images,node_analyzer_agent,node_analysis_loop,node_analysis_process,node_selector,node_single_analyzer,node_analyze_tool,node_analysis_save,node_save_tool,node_style_guide toneAmber
class node_prompt_agent,node_youtube,node_openai toneMint
class node_asset_callback,node_assets,node_image_agent,node_create_image,node_generated_images toneRose
class node_creator toneIndigo
```

## Components

### Workflow Coordination

- [Thumbnail Manager](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/agent.py): `youtube_thumbnail_agent/agent.py`

### Reference Analysis

- [Channel Scraper](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_scraper/agent.py): `youtube_thumbnail_agent/sub_agents/thumbnail_scraper/agent.py`
- [Scrape Channel](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_scraper/tools/scrape_channel.py): `youtube_thumbnail_agent/sub_agents/thumbnail_scraper/tools/scrape_channel.py`
- [Reference Images](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/constants.py): `youtube_thumbnail_agent/constants.py`
- [Thumbnail Analyzer](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/agent.py): `youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/agent.py`
- [Analysis Loop](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/agent.py): `youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/agent.py`
- [Analysis Process](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/analysis_process_agent.py): `youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/analysis_process_agent.py`
- [Thumbnail Selector](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/thumbnail_selector_agent.py): `youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/thumbnail_selector_agent.py`
- [Single Thumbnail Analysis](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/single_thumbnail_analyzer_agent.py): `youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/single_thumbnail_analyzer_agent.py`
- [Load Thumbnail](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/tools/analyze_thumbnail.py): `youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/tools/analyze_thumbnail.py`
- [Save Analysis](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/save_analysis_agent.py): `youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/save_analysis_agent.py`
- [Analysis Storage Tool](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/tools/save_analysis.py): `youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/tools/save_analysis.py`
- [Style Guide](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/style_guide_generator_agent.py): `youtube_thumbnail_agent/sub_agents/thumbnail_analyzer_agent/sub_agents/style_guide_generator_agent.py`

### Prompt Design

- [Prompt Generator](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/prompt_generator/agent.py): `youtube_thumbnail_agent/sub_agents/prompt_generator/agent.py`

### Image Generation

- [User Image Callback](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/shared_lib/callbacks.py): `youtube_thumbnail_agent/shared_lib/callbacks.py`
- [User Assets](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/constants.py): `youtube_thumbnail_agent/constants.py`
- [Image Generator](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/generate_image_agent/agent.py): `youtube_thumbnail_agent/sub_agents/generate_image_agent/agent.py`
- [Create or Edit Image](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/sub_agents/generate_image_agent/tools/create_image.py): `youtube_thumbnail_agent/sub_agents/generate_image_agent/tools/create_image.py`
- [Generated Thumbnails](https://github.com/bhancockio/adk-youtube-thumbnail-agent/blob/main/youtube_thumbnail_agent/constants.py): `youtube_thumbnail_agent/constants.py`

### Other components

- **Creator**
- **YouTube Data API**
- **OpenAI Image API**

## Connections

- Creator → Thumbnail Manager: provides requests
- Thumbnail Manager → Creator: asks for details
- Thumbnail Manager → Channel Scraper: delegates collection
- Channel Scraper → Scrape Channel: invokes
- Scrape Channel → YouTube Data API: queries channel
- Scrape Channel → YouTube Data API: downloads thumbnails
- Scrape Channel → Reference Images: writes thumbnails
- Thumbnail Manager → Thumbnail Analyzer: delegates analysis
- Thumbnail Analyzer → Analysis Loop: runs iteratively
- Analysis Loop → Analysis Process: repeats
- Analysis Process → Thumbnail Selector: selects thumbnail
- Analysis Process → Single Thumbnail Analysis: runs analysis
- Single Thumbnail Analysis → Load Thumbnail: loads image
- Load Thumbnail → Reference Images: reads thumbnail
- Analysis Process → Save Analysis: saves result
- Save Analysis → Analysis Storage Tool: uses tool
- Thumbnail Analyzer → Style Guide: synthesizes analyses
- Thumbnail Manager → Prompt Generator: delegates prompting
- Prompt Generator → Creator: collects video details
- Thumbnail Manager → Image Generator: delegates generation
- Image Generator → Create or Edit Image: invokes
- User Image Callback → User Assets: saves uploaded images
- Create or Edit Image → User Assets: reads references
- Create or Edit Image → OpenAI Image API: generates or edits
- Create or Edit Image → Generated Thumbnails: saves output
- Thumbnail Manager → Creator: presents result