# krishgaur1354/yt-short-generator-adk architecture

> Architecture diagram of the GitHub repository krishgaur1354/yt-short-generator-adk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krishgaur1354/yt-short-generator-adk
- Repository: https://github.com/krishgaur1354/yt-short-generator-adk

## Overview

##### Project type and purpose
- This is a single‐service “automation bot” application written in Python. It exposes a Telegram Bot interface to let a user request YouTube Shorts. Internally, it orchestrates calls to:
- Google ADK (Gemini) for script generation
- A text-to-speech engine for voiceover
- An image search API (Unsplash or similar)
- A video generator that stitches images + audio into a Short
- The YouTube Data API to upload the video
- Optionally, an n8n webhook for external workflow automation

##### File structure
- Top-level scripts:
- telegram_bot.py – the main orchestrator (entry point)
- image_search.py, script_generator.py, video_generator.py, youtube_uploader.py – standalone/test wrappers around each core module
- src/api/youtube.py – encapsulates YouTube Data API calls
- src/utils/script.py – wraps ADK/Gemini LlmAgent to produce text scripts
- src/utils/images.py – handles image search/download (Unsplash or other)
- src/video/generator.py – assembles audio + images into a video file
- config.env.example – environment variables for API keys and tokens

##### README for technical stack
- Python 3.9+
- Telegram Bot API
- Google APIs: Gemini LLM, YouTube Data API, Text-to-Speech
- Optional: Unsplash API, n8n Webhook

##### Main components and their interactions
a. Telegram Bot Interface (telegram_bot.py)
- Receives `/create` commands
- Manages dialogue (ask title/description)
- Orchestrates downstream modules
b. Script Generator (src/utils/script.py)
- Calls Google ADK/Gemini LlmAgent via HTTP or SDK
- Returns a script text
c. Text-to-Speech Engine
- Could be Google Cloud Text-to-Speech or another TTS service
- Consumes script text → returns audio file
d. Image Search Module (src/utils/images.py)
- Calls Unsplash or another image API
- Retrieves and caches images
e. Video Generator (src/video/generator.py)
- Takes audio + images → produces a short video (e.g., using MoviePy or FFMPEG)
f. YouTube Uploader (src/api/youtube.py & youtube_uploader.py)
- Uses OAuth credentials to upload as a YouTube Short
g. n8n Webhook Integration (optional)
- Posts JSON metadata to configured n8n webhook on success/failure

##### Architectural patterns and design principles
- Modular design: each concern lives in its own module
- Single-process, event-driven orchestration by telegram_bot.py
- Clear separation between I/O (APIs), business logic (script/video generation), and orchestration
- Use of config.env for all secrets/configuration – no hard-coded keys

##### Detailed capture of essential elements
- Do not oversimplify: show each of the five core processing modules
- Optional branch to n8n webhook
- External API keys flowing into the config store

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Subgraphs
    subgraph "Internal Modules"
        Bot["Telegram Bot Interface"]:::core
        Script["Script Generation Module"]:::core
        TTS["Text-to-Speech Engine"]:::core
        Img["Image Search Module"]:::core
        Video["Video Generator Module"]:::core
        Uploader["YouTube Uploader Module"]:::core
        Config["Configuration Store"]:::config
    end

    subgraph "External Services"
        TGAPI["Telegram API"]:::external
        ADK["Google ADK (Gemini)"]:::external
        TTSAPI["Text-to-Speech API"]:::external
        ImgAPI["Image Search API"]:::external
        YTAPI["YouTube Data API"]:::external
        N8N["n8n Webhook"]:::external
    end

    %% Flow
    TGAPI -->|"updates"| Bot
    Bot -->|"HTTP: generate script"| Script
    Script -->|"LLM request"| ADK
    ADK -->|"script text"| Script
    Script -->|"script text"| TTS
    Script -->|"script text"| Img
    TTS -->|"synthesized audio"| Video
    Img -->|"retrieved images"| Video
    TTS -->|"send to TTS API"| TTSAPI
    TTSAPI -->|"audio file"| TTS
    Img -->|"search images"| ImgAPI
    ImgAPI -->|"image data"| Img
    Video -->|"video file"| Uploader
    Uploader -->|"upload request"| YTAPI
    YTAPI -->|"upload response"| Uploader
    Uploader -->|"metadata JSON"| N8N

    %% Config connections
    Config --> Bot
    Config --> Script
    Config --> TTS
    Config --> Img
    Config --> Video
    Config --> Uploader

    %% Click Events
    click Bot "https://github.com/krishgaur1354/yt-short-generator-adk/blob/main/telegram_bot.py"
    click Script "https://github.com/krishgaur1354/yt-short-generator-adk/blob/main/src/utils/script.py"
    click Script "https://github.com/krishgaur1354/yt-short-generator-adk/blob/main/script_generator.py"
    click Img "https://github.com/krishgaur1354/yt-short-generator-adk/blob/main/src/utils/images.py"
    click Img "https://github.com/krishgaur1354/yt-short-generator-adk/blob/main/image_search.py"
    click Video "https://github.com/krishgaur1354/yt-short-generator-adk/blob/main/src/video/generator.py"
    click Video "https://github.com/krishgaur1354/yt-short-generator-adk/blob/main/video_generator.py"
    click Uploader "https://github.com/krishgaur1354/yt-short-generator-adk/blob/main/src/api/youtube.py"
    click Uploader "https://github.com/krishgaur1354/yt-short-generator-adk/blob/main/youtube_uploader.py"
    click Config "https://github.com/krishgaur1354/yt-short-generator-adk/blob/main/config.env.example"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#3399FF,stroke-width:1px
    classDef external fill:#FFE6CC,stroke:#FF9933,stroke-width:1px
    classDef config fill:#E8F5E9,stroke:#4CAF50,stroke-width:1px
```
