# corvohisui/qa-youtube-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/corvohisui/qa-youtube-chatbot
- Repository: https://github.com/corvohisui/qa-youtube-chatbot

## Overview

##### Project type and purpose
- From the file tree we see:
- A top‑level `app.py`/`main.py`, a `presentation/` folder, an `agents/` folder, and a `tools/` folder.
- Tools for interacting with YouTube and ChromaDB, and several “agent” modules for QA and graph‑based workflows.
- This tells us it’s an AI‑driven QA system that:
- Ingests YouTube videos (via the tools)
- Stores/queries embeddings in ChromaDB
- Uses LLM‑backed “agents” to handle different QA or graph‑building tasks
- Exposes a presentation layer (likely a CLI or web UI) via `app.py`/`main.py`

##### File structure
- Top level:
- `presentation/` – UI assets or templates
- `app.py` + `main.py` – entry points (API or CLI)
- `config.py` + `config.yaml` – configuration management
- `requirements.txt` – dependencies
- `/agents`:
- `qa_agent.py`, `structured_agent.py` – orchestrators that drive LLM calls & tool usage
- `qa_graph.py`, `multi_video_graph.py` – domain‑specific routines to build/query knowledge graphs
- `/tools`:
- `youtube_tool.py`, `youtube_metadata.py` – fetch video/transcript data from YouTube API
- `chromadb_tool.py` – read/write embeddings to ChromaDB
- `utils.py`, `clear_cache.py` – support utilities

##### Available documentation
- No README content provided, so we rely on file and naming conventions to infer responsibilities.

##### Key reminder
- Be very detailed: include every folder/module as a component if it has distinct behavior.
- Showing how data traverses from user input all the way to external systems and back.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        Presentation["Presentation Layer"]:::presentation
    end

    %% Orchestrator Layer
    subgraph "Orchestrator Layer"
        API["API Orchestrator (app.py)"]:::orchestrator
        CLI["CLI/Web Launcher (main.py)"]:::orchestrator
    end

    %% Configuration
    subgraph "Configuration"
        ConfigFile["Configuration File (config.yaml)"]:::config
        ConfigLoader["Runtime Config Loader (config.py)"]:::config
    end

    %% Agent Layer
    subgraph "Agent Layer"
        QA["QA Agent"]:::agent
        Struct["Structured Data Agent"]:::agent
        KGQA["Knowledge-Graph QA Routines"]:::agent
        MVG["Multi-Video Graph Builder"]:::agent
    end

    %% Tools Layer
    subgraph "Tools Layer"
        YTFetch["YouTube Video Fetching Tool"]:::tool
        YTMeta["YouTube Metadata/Transcript Helper"]:::tool
        Chroma["ChromaDB Embedding Store Adapter"]:::tool
        Utils["Utility Functions"]:::tool
        CacheUtil["Cache Management Utility"]:::tool
    end

    %% External Services / Data Stores
    subgraph "External Services / Data Stores"
        YouTubeAPI["YouTube API"]:::external
        ChromaDB["ChromaDB"]:::external
        LocalCache["Local Cache (fs)"]:::external
        LLM["LLM API"]:::external
    end

    %% Documentation
    Requirements["requirements.txt"]:::doc
    Readme["README.md"]:::doc

    %% Connections
    Presentation -->|uses| API
    Presentation -->|uses| CLI

    API -->|dispatches tasks| QA
    API -->|dispatches tasks| Struct
    API -->|dispatches tasks| KGQA
    API -->|dispatches tasks| MVG

    QA -->|calls tools| YTFetch
    QA -->|calls tools| YTMeta
    QA -->|calls tools| Chroma
    QA -->|calls tools| Utils
    QA -->|calls| LLM

    Struct -->|calls tools| YTFetch
    Struct -->|calls tools| YTMeta
    Struct -->|calls tools| Chroma
    Struct -->|calls tools| Utils
    Struct -->|calls| LLM

    KGQA -->|calls tools| YTFetch
    KGQA -->|calls tools| YTMeta
    KGQA -->|calls tools| Chroma
    KGQA -->|calls tools| Utils
    KGQA -->|calls| LLM

    MVG -->|calls tools| YTFetch
    MVG -->|calls tools| YTMeta
    MVG -->|calls tools| Chroma
    MVG -->|calls tools| Utils
    MVG -->|calls| LLM

    YTFetch -->|fetches data| YouTubeAPI
    YTMeta -->|fetches metadata| YouTubeAPI
    Chroma -->|reads/writes embeddings| ChromaDB
    CacheUtil -->|manages| LocalCache

    ConfigFile -->|loaded by| ConfigLoader
    ConfigLoader -->|provides config to| QA
    ConfigLoader -->|provides config to| Struct
    ConfigLoader -->|provides config to| KGQA
    ConfigLoader -->|provides config to| MVG
    ConfigLoader -->|provides config to| YTFetch
    ConfigLoader -->|provides config to| YTMeta
    ConfigLoader -->|provides config to| Chroma
    ConfigLoader -->|provides config to| Utils
    ConfigLoader -->|provides config to| CacheUtil

    %% Click Events
    click Presentation "https://github.com/corvohisui/qa-youtube-chatbot/tree/main/presentation/"
    click API "https://github.com/corvohisui/qa-youtube-chatbot/blob/main/app.py"
    click CLI "https://github.com/corvohisui/qa-youtube-chatbot/blob/main/main.py"
    click ConfigFile "https://github.com/corvohisui/qa-youtube-chatbot/blob/main/config.yaml"
    click ConfigLoader "https://github.com/corvohisui/qa-youtube-chatbot/blob/main/config.py"
    click QA "https://github.com/corvohisui/qa-youtube-chatbot/blob/main/agents/qa_agent.py"
    click Struct "https://github.com/corvohisui/qa-youtube-chatbot/blob/main/agents/structured_agent.py"
    click KGQA "https://github.com/corvohisui/qa-youtube-chatbot/blob/main/agents/qa_graph.py"
    click MVG "https://github.com/corvohisui/qa-youtube-chatbot/blob/main/agents/multi_video_graph.py"
    click YTFetch "https://github.com/corvohisui/qa-youtube-chatbot/blob/main/tools/youtube_tool.py"
    click YTMeta "https://github.com/corvohisui/qa-youtube-chatbot/blob/main/tools/youtube_metadata.py"
    click Chroma "https://github.com/corvohisui/qa-youtube-chatbot/blob/main/tools/chromadb_tool.py"
    click Utils "https://github.com/corvohisui/qa-youtube-chatbot/blob/main/tools/utils.py"
    click CacheUtil "https://github.com/corvohisui/qa-youtube-chatbot/blob/main/tools/clear_cache.py"
    click Requirements "https://github.com/corvohisui/qa-youtube-chatbot/blob/main/requirements.txt"
    click Readme "https://github.com/corvohisui/qa-youtube-chatbot/blob/main/README.md"

    %% Styles
    classDef presentation fill:#add8e6,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#90ee90,stroke:#333,stroke-width:1px
    classDef agent fill:#90ee90,stroke:#333,stroke-width:1px
    classDef tool fill:#ffffe0,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef config fill:#ffd580,stroke:#333,stroke-width:1px
    classDef doc fill:#e6e6fa,stroke:#333,stroke-width:1px
```
