# ashvinbari/youtube_agent architecture

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

- Interactive diagram: https://gitdiagram.com/ashvinbari/youtube_agent
- Repository: https://github.com/ashvinbari/youtube_agent

## Overview

##### What this project is (type + purpose)
This is a **single-service, UI-driven Streamlit application** (Python) that acts as an “AI agent” to **recommend the best YouTube tutorials** for a user-provided topic and difficulty level. The app’s core capability is delegated to the **Tavily API** (external search/content extraction). The UI renders a “best pick” plus additional recommendations, including thumbnails and links that ultimately route users to **YouTube**.

Given the tiny file tree (`app.py`, `requirements.txt`, `README.md`), the architecture is intentionally simple: **one Streamlit container + external API dependencies**.

##### How to read the file structure into architecture
From the file tree:
- `app.py` → **All application logic and UI** live here (input handling, calling Tavily, ranking/selection, rendering results).
- `requirements.txt` → Defines runtime dependencies (Streamlit, Tavily client/requests, etc.). This maps to the **runtime container** and external libs.

- A single **UI+backend combined** Streamlit service (not separate frontend/backend).
- External services: **Tavily API** (mandatory), **YouTube** (destination links + thumbnails/metadata source depending on how Tavily returns results).

##### Streamlit Server (Python runtime)
- “UI Layer” (Streamlit widgets/pages)
- “Agent/Recommendation Logic” (query building, filtering, picking best)
- “Integration Layer” (Tavily API client / HTTP requests)
##### YouTube (External)
- Mostly a link-out target; optionally the “content source” behind Tavily search results.

##### Secrets/Config Source
- Environment variables / Streamlit secrets (recommended) vs hardcoded key (current)
##### Deployment Environment
- Logging, error handling, rate-limit handling (even if minimal)

##### User → Browser → Streamlit App
- Inputs: `topic`, `difficulty level`, “Find Best Video” action
##### Streamlit App → Tavily API
- Outbound HTTPS request containing search query and parameters (and API key)
##### Tavily API → Streamlit App
- Response: list of candidate results (titles, URLs, snippets/metadata; possibly thumbnails if returned)
##### Streamlit App (internal)
- Ranking/selection: choose “best pick” (e.g., highest view / most relevant)
- Prepare “additional recommendations”
##### Streamlit App → Browser
- Render: thumbnail, title, description, “Watch Video” links
##### Browser → YouTube
- When user clicks a recommendation, they navigate to YouTube

- **Streamlit App → Secrets/Env**
- *(Optional)* **Streamlit App ↔ Cache**

##### Architectural pattern to highlight
- **“Thin UI + orchestration service”**: Streamlit is both presentation and controller/orchestrator.
- **External-API-centric**: core intelligence/search is delegated to Tavily; the app is an integration + ranking + visualization layer.

- Where the key should live (env var / Streamlit secrets)
- That the Streamlit server is the one holding the secret (not the browser)

An annotation near Tavily:
- “Rate limits / latency / failure modes” (just a note) to justify potential caching/retry logic.

##### Final “don’t overthink it” checklist (specific to this repo)
- Treat **Streamlit** as both frontend and backend.
- Always show **Tavily** as the core external dependency.
- **YouTube** as link-out destination (and implied content source).
- **Secrets/Env** explicitly due to the README warning.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =============== System Context (C4 L1) ===============
  subgraph SC["System Context (C4 Level 1)"]
    direction TB

    U["User (Learner)"]:::person
    B["Web Browser"]:::client

    subgraph APPCTX["AI Agent for YouTube Tutorials (Single Streamlit Service)"]
      direction TB
      S["Streamlit App (UI + Backend Combined)"]:::firstparty
    end

    T["Tavily API (External Search/Extraction)"]:::external
    Y["YouTube (External)"]:::external

    subgraph OPS["Ops / Environment"]
      direction TB
      SEC["Secrets / Config Source\n(TAVILY_API_KEY via env/Streamlit secrets; avoid hardcoding)"]:::ops
      DEP["Deployment Environment\n(Local machine or hosted Streamlit)"]:::ops
      OBS["Observability\n(logging, error handling, rate-limit awareness)"]:::ops
    end

    U -->|uses| B
    B <--> |"HTTP: Streamlit UI"| S

    S -->|"HTTPS: search_query + API_key"| T
    T -->|"results: titles + urls + metadata"| S

    S -->|reads_secret| SEC
    DEP -->|runs| S
    S -->|"logs/errors"| OBS

    B -->|click_watch_video| Y
  end

  %% =============== Container / Component (C4 L2/L3-ish) ===============
  subgraph CC["Container / Component View (Inside app.py)"]
    direction TB

    subgraph APPINT["Streamlit App Internals"]
      direction TB

      UI["UI Layer\nStreamlit widgets (topic, difficulty, button)\nresults rendering"]:::firstparty
      QB["Query Builder\n(topic+difficulty -> search phrase)"]:::firstparty
      INT["Integration Layer\nTavily client / HTTP requests"]:::firstparty
      RK["Agent / Recommendation Logic\nfiltering + ranking\n(best pick + alternatives)"]:::firstparty
      PR["Presenter\ncards, thumbnails, links"]:::firstparty
      CACHE["Optional: Streamlit Cache\n(in-memory, reduces API calls)"]:::ops

      UI -->|build_query| QB
      QB -->|call_search| INT
      INT -->|raw_results| RK
      RK -->|selected_items| PR
      PR -->|render_to_ui| UI

      UI -->|"optional_cache_read/write"| CACHE
      INT -->|"optional_cache_read/write"| CACHE
    end

    INT -->|"HTTPS: search_query + API_key"| T
    T -->|results| INT

    PR -->|links_to| B
    B -->|navigate_to| Y

    SEC -->|provides_key| INT

    NOTE_T["Note: Tavily constraints\n(rate limits, latency, failures)\n-> consider retry/backoff + caching"]:::note
    T -.->|non_functional_constraints| NOTE_T
  end

  %% Explicit requirements node for mapping
  DEPS["Runtime Dependencies\n(Streamlit, Tavily client/requests, etc.)"]:::ops
  S -.->|imports| DEPS

  %% =============== Click Events (from component_mapping) ===============
  click S "https://github.com/ashvinbari/youtube_agent/blob/main/app.py"
  click UI "https://github.com/ashvinbari/youtube_agent/blob/main/app.py"
  click QB "https://github.com/ashvinbari/youtube_agent/blob/main/app.py"
  click RK "https://github.com/ashvinbari/youtube_agent/blob/main/app.py"
  click INT "https://github.com/ashvinbari/youtube_agent/blob/main/app.py"
  click PR "https://github.com/ashvinbari/youtube_agent/blob/main/app.py"
  click CACHE "https://github.com/ashvinbari/youtube_agent/blob/main/app.py"

  click SEC "https://github.com/ashvinbari/youtube_agent/blob/main/README.md"
  click DEP "https://github.com/ashvinbari/youtube_agent/blob/main/.venv"
  click OBS "https://github.com/ashvinbari/youtube_agent/blob/main/README.md"
  click NOTE_T "https://github.com/ashvinbari/youtube_agent/blob/main/README.md"

  click B "https://github.com/ashvinbari/youtube_agent/blob/main/README.md"
  click U "https://github.com/ashvinbari/youtube_agent/blob/main/README.md"
  click T "https://github.com/ashvinbari/youtube_agent/blob/main/README.md"
  click Y "https://github.com/ashvinbari/youtube_agent/blob/main/README.md"

  click DEPS "https://github.com/ashvinbari/youtube_agent/blob/main/requirements.txt"

  %% =============== Styles ===============
  classDef firstparty fill:#1e88e5,stroke:#0d47a1,stroke-width:2px,color:#ffffff;
  classDef external fill:#fb8c00,stroke:#e65100,stroke-width:2px,color:#ffffff;
  classDef ops fill:#90a4ae,stroke:#455a64,stroke-width:2px,color:#0b0f12;
  classDef client fill:#64b5f6,stroke:#1e88e5,stroke-width:2px,color:#0b0f12;
  classDef person fill:#1565c0,stroke:#0d47a1,stroke-width:2px,color:#ffffff;
  classDef note fill:#fff3e0,stroke:#ef6c00,stroke-width:1.5px,color:#3e2723;
```
