# keemsmile/youtubewriter architecture

> Architecture diagram of the GitHub repository keemsmile/youtubewriter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/keemsmile/youtubewriter
- Repository: https://github.com/keemsmile/youtubewriter

## Overview

##### Project Type and Purpose
- This is a full-stack, AI-powered content generation application that takes YouTube videos (or transcripts) as input and outputs various content pieces including articles, SEO recommendations, and social media posts.
- Its primary functionality revolves around processing video transcripts using specialized AI agents for distinct tasks (transcript processing, SEO optimization, journalism-style article creation, content editing, and social post generation) combined with a modern, responsive Streamlit UI.

##### Key Components
- Frontend/UI:
- The Streamlit-based user interface (app.py) responsible for taking inputs (YouTube URL or transcript), displaying progress indicators, and showing generated outputs.
- Visual features like gradient-based design, dark mode, and expandable detailed outputs.
- Backend/Processing Core:
- AI Agents: Represent each specialized agent as a component. Include:
- TranscriptAgent (agents/transcript_agent.py) – for fetching and processing YouTube transcripts.
- SEOAgent (agents/seo_agent.py or swarm_agents/seo_agent.py) – for generating SEO-friendly content.
- JournalistAgent (agents/journalist_agent.py or swarm_agents/journalist_agent.py) – for writing the primary article.
- EditorAgent (agents/editor_agent.py) – for polishing and refining the generated content.
- SocialMediaAgent (agents/social_media_agent.py or swarm_agents/social_media_agent.py) – for creating platform-specific posts.
- Swarm Integration & Orchestration:
- The swarm_agents directory suggests an alternative or additional orchestration layer (swarm_agents/orchestrator.py) that coordinates agent interactions. Clearly include an orchestration component indicating the control flow among agents.
- External Integrations:
- YouTube Transcript API: for automatic transcript fetching.
- OpenAI API: utilized by various agents for AI-powered text generation.
- Configuration & Utility:
- A configuration module (utils/config.py) that sets up important parameters and environment variables (like setting up the OpenAI API key).

##### Relationship and Data Flow
- The input is then routed to the TranscriptAgent to retrieve or verify the transcript.
- Next, the flow splits into parallel processing by the specialized agents:
- The SEOAgent processes the text for search engine optimization.
- The JournalistAgent generates the main article while the EditorAgent refines it.
- The SocialMediaAgent creates tailored posts.
- Optionally, if the Swarm integration layer is used, illustrate how the Orchestrator delegates work to swarm_agents.
- Final outputs from these agents are then collected and rendered back in the UI.

##### Architectural Patterns and Design Principles
- Modular Design: Emphasize the separation of concerns whereby each agent performs a distinct, defined task.
- Agent-based Architecture: Illustrate how individual AI agents operate both independently and collaboratively under orchestration.
- Clear Separation between Frontend (UI) and Backend (processing agents) even though the application is driven by Python scripts.
- Extensibility: Highlight how new agents or integrations can be seamlessly added (noting the parallel structure in both “agents” and “swarm_agents” directories).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI["Streamlit UI (app.py)"]:::frontend
    end

    %% Backend/Processing Core
    subgraph "Backend/Processing Core"
        TA["TranscriptAgent"]:::agent
        ORCH["Swarm Orchestrator"]:::orchestrator
        SEO["SEOAgent"]:::agent
        JRN["JournalistAgent"]:::agent
        ED["EditorAgent"]:::agent
        SM["SocialMediaAgent"]:::agent
    end

    %% Integration & Configuration Layer
    subgraph "Integration & Configuration Layer"
        YT["YouTube Transcript API"]:::integration
        OAI["OpenAI API"]:::integration
        CONF["Configuration & Utility (utils/config.py)"]:::config
    end

    %% Data Flow Connections
    UI -->|"posts_input"| TA
    YT -->|"fetches_transcript"| TA
    CONF -->|"configures"| TA
    TA -->|"sends_transcript"| ORCH
    ORCH -->|"delegates_to"| SEO
    ORCH -->|"delegates_to"| JRN
    ORCH -->|"delegates_to"| ED
    ORCH -->|"delegates_to"| SM
    CONF -->|"configures"| SEO
    CONF -->|"configures"| JRN
    CONF -->|"configures"| ED
    CONF -->|"configures"| SM
    SEO -->|"uses"| OAI
    JRN -->|"uses"| OAI
    ED -->|"uses"| OAI
    SM -->|"uses"| OAI
    SEO -->|"results_returned"| UI
    JRN -->|"results_returned"| UI
    ED -->|"results_returned"| UI
    SM -->|"results_returned"| UI

    %% Click Events
    click UI "https://github.com/keemsmile/youtubewriter/blob/main/app.py"
    click TA "https://github.com/keemsmile/youtubewriter/blob/main/agents/transcript_agent.py"
    click SEO "https://github.com/keemsmile/youtubewriter/blob/main/agents/seo_agent.py"
    click JRN "https://github.com/keemsmile/youtubewriter/blob/main/agents/journalist_agent.py"
    click ED "https://github.com/keemsmile/youtubewriter/blob/main/agents/editor_agent.py"
    click SM "https://github.com/keemsmile/youtubewriter/blob/main/agents/social_media_agent.py"
    click ORCH "https://github.com/keemsmile/youtubewriter/blob/main/swarm_agents/orchestrator.py"
    click CONF "https://github.com/keemsmile/youtubewriter/blob/main/utils/config.py"

    %% Styles
    classDef frontend fill:#a9d0f5,stroke:#333,stroke-width:2px;
    classDef agent fill:#c3f0ca,stroke:#333,stroke-width:2px;
    classDef orchestrator fill:#ffe699,stroke:#333,stroke-width:2px;
    classDef integration fill:#f9d6d5,stroke:#333,stroke-width:2px;
    classDef config fill:#d7bde2,stroke:#333,stroke-width:2px;
```
