# xmyoot/ai-yt-sum architecture

> Architecture diagram of the GitHub repository xmyoot/ai-yt-sum, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xmyoot/ai-yt-sum
- Repository: https://github.com/xmyoot/ai-yt-sum

## Overview

##### Project type & purpose (from file tree + README)
This is a small full-stack web application:

- **Frontend**: `client/` is a **React + TypeScript** app built with **Vite** (`client/vite.config.ts`, `src/main.tsx`, `src/App.tsx`, MUI-ish theme hints in `src/theme.tsx`).
- **Backend**: `server/` is a **Python API** (very likely Flask/FastAPI style) with:
- `server/app.py` = web server / HTTP endpoints
- `server/summarizer.py` = summarization core logic (domain layer)
- `server/test_app.py` = backend tests
- **Purpose**: user submits a **YouTube URL**, system fetches video content (often transcript/captions) and returns an **AI-generated summary**.

From the tree, the natural architectural separation is:

##### Frontend (client/)
Key components to represent:
- **UI Entry**: `index.html` → `src/main.tsx`
- **Main UI**: `src/App.tsx` (likely contains URL input + button + summary rendering)
- **Styling/Theming**: `src/theme.tsx`, `App.css`, `index.css`
- **Build tooling**: `vite.config.ts`, `package.json`

##### Backend (server/)
Key components to represent:
- **HTTP layer**: `app.py` defines routes such as `/summarize` (name may differ; confirm in file)
- **Domain/service layer**: `summarizer.py` contains:
- YouTube URL parsing / video id extraction
- transcript retrieval
- summarization logic (LLM call or local model)

- In `app.py`, identify:
- framework (Flask/FastAPI)
- CORS setup (common for React ↔ API)
- In `summarizer.py`, identify:
- whether it uses **YouTube Transcript API**, **yt-dlp**, **YouTube Data API**, etc.
- whether it calls **OpenAI / Anthropic / Gemini** or a local model
- where secrets come from (env vars, config)

##### Optional but often important
- **Environment/Secrets** (API keys)
- **Logging/Monitoring** (even if not implemented, note “stdout logs”)

Because the instruction is “don’t overthink; separate into as many components as possible,” I’d explicitly split the backend into **HTTP Controller** vs **Summarizer Service** vs **External Integrations** rather than one big backend blob.

##### Browser → React App
“User enters YouTube URL; clicks Summarize”
##### React App → Python API Server
“POST /summarize { url }” (use actual route once confirmed)
##### API Server → Summarizer Module
“validate URL, extract videoId, orchestrate pipeline”
##### Summarizer Module → YouTube (external)
“fetch transcript/captions or metadata”
##### Summarizer Module → LLM Provider (external)
“send transcript; request summary”
##### LLM Provider → Summarizer Module
“summary text”
##### Summarizer Module → API Server
“summary result (and maybe title, timestamps)”
##### API Server → React App
“JSON response”
##### React App → Browser UI
“render summary”

- “Transcript unavailable” → return error or fallback path
- “LLM API failure / rate limit” → error response
- “Invalid URL” → 400 response

##### Architectural patterns to highlight (as evidenced by structure)
Even without code contents, the structure strongly suggests:

- **Client–Server** architecture
- Backend with a thin **HTTP layer** (`app.py`) delegating to a **service module** (`summarizer.py`)
- **Integration architecture**: backend integrates with external providers (YouTube + AI)
- **Testable boundary**: `test_app.py` implies API endpoints are test targets

- Presentation/API layer (routes)
- Service layer (summarizer orchestration)
- External adapters (YouTube adapter, LLM adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =======================
  %% External Actor / Runtime
  %% =======================
  U["User"]:::actor
  B["Web Browser"]:::runtime

  %% =======================
  %% Frontend (Client)
  %% =======================
  subgraph "Frontend: React + TypeScript (Vite)"
    FE["React Web App (client/)"]:::frontend

    subgraph "UI Entry & Bootstrap"
      FE_HTML["HTML Shell"]:::file
      FE_MAIN["React Entrypoint"]:::file
    end

    subgraph "UI Components"
      FE_APP["Main UI: URL input + summary view"]:::file
      FE_TIP["Supporting UI: ProTip"]:::file
    end

    subgraph "Styling & Theme"
      FE_THEME["Theme Provider / Theme config"]:::file
      FE_CSS_GLOBAL["Global CSS"]:::file
      FE_CSS_APP["App CSS"]:::file
      FE_ASSETS["Static Assets"]:::dir
    end

    subgraph "Build & Dependencies"
      FE_VITE["Vite Config"]:::file
      FE_PKG["package.json"]:::file
    end
  end

  %% =======================
  %% Backend (Server)
  %% =======================
  subgraph "Backend: Python API"
    BE_API["HTTP API Server (Routes/Controllers)"]:::backend
    BE_SUM["Summarizer Service (Orchestration/Domain)"]:::service

    subgraph "External Adapters (in code)"
      AD_YT["YouTube Transcript Retrieval (adapter)"]:::adapter
      AD_LLM["LLM Client (adapter)"]:::adapter
    end

    BE_TESTS["Backend Tests (API endpoint tests)"]:::test
    NOTE_STATELESS["Stateless API\n(no DB in repo)"]:::note
  end

  %% =======================
  %% External Services
  %% =======================
  YT["YouTube (Transcript/Metadata)"]:::external
  LLM["LLM Provider API"]:::external
  ENV["Environment / Secrets\n(API keys via env vars)"]:::external

  %% =======================
  %% Primary Request Flow
  %% =======================
  U -->|"enters YouTubeURL"| B
  B -->|"loads UI"| FE_HTML
  FE_HTML -->|"bootstraps"| FE_MAIN
  FE_MAIN -->|"renders"| FE_APP

  FE_APP -->|"HTTP_POST_/summarize {url}"| BE_API
  BE_API -->|"validateURL_extractVideoId_orchestrate"| BE_SUM

  BE_SUM -->|"fetchTranscript"| AD_YT
  AD_YT -->|"requestCaptions"| YT
  YT -->|"transcriptText"| AD_YT
  AD_YT -->|"transcriptText"| BE_SUM

  BE_SUM -->|"summarize(transcript)"| AD_LLM
  AD_LLM -->|"API_call_with_transcript"| LLM
  LLM -->|"summaryText"| AD_LLM
  AD_LLM -->|"summaryText"| BE_SUM

  BE_SUM -->|"result {summary,...}"| BE_API
  BE_API -->|"HTTP_200_JSON {summary}"| FE_APP
  FE_APP -->|"renderSummary"| B

  %% =======================
  %% Config/Secrets & Tests
  %% =======================
  ENV -.->|"readsAPIKeys"| BE_API
  ENV -.->|"readsAPIKeys"| BE_SUM
  BE_TESTS -.->|"testsRoutes"| BE_API

  %% =======================
  %% Error / Edge Flows (dotted)
  %% =======================
  FE_APP -.->|"invalidURL_400"| BE_API
  BE_SUM -.->|"transcriptUnavailable_error"| BE_API
  BE_SUM -.->|"llmFailure_rateLimit_error"| BE_API

  %% =======================
  %% Notes / Annotations
  %% =======================
  BE_API -.->|"note"| NOTE_STATELESS

  %% =======================
  %% Click Events (from mapping)
  %% =======================
  click FE "https://github.com/xmyoot/ai-yt-sum/tree/main/client/"
  click FE_HTML "https://github.com/xmyoot/ai-yt-sum/blob/main/client/index.html"
  click FE_MAIN "https://github.com/xmyoot/ai-yt-sum/blob/main/client/src/main.tsx"
  click FE_APP "https://github.com/xmyoot/ai-yt-sum/blob/main/client/src/App.tsx"
  click FE_CSS_GLOBAL "https://github.com/xmyoot/ai-yt-sum/blob/main/client/src/index.css"
  click FE_CSS_APP "https://github.com/xmyoot/ai-yt-sum/blob/main/client/src/App.css"
  click FE_THEME "https://github.com/xmyoot/ai-yt-sum/blob/main/client/src/theme.tsx"
  click FE_TIP "https://github.com/xmyoot/ai-yt-sum/blob/main/client/src/ProTip.tsx"
  click FE_ASSETS "https://github.com/xmyoot/ai-yt-sum/tree/main/client/src/assets/"
  click FE_VITE "https://github.com/xmyoot/ai-yt-sum/blob/main/client/vite.config.ts"
  click FE_PKG "https://github.com/xmyoot/ai-yt-sum/blob/main/client/package.json"
  click BE_API "https://github.com/xmyoot/ai-yt-sum/blob/main/server/app.py"
  click BE_SUM "https://github.com/xmyoot/ai-yt-sum/blob/main/server/summarizer.py"
  click BE_TESTS "https://github.com/xmyoot/ai-yt-sum/blob/main/server/test_app.py"

  %% =======================
  %% Styles
  %% =======================
  classDef actor fill:#0b1220,stroke:#93c5fd,color:#e5e7eb,stroke-width:1.5px
  classDef runtime fill:#111827,stroke:#60a5fa,color:#f9fafb,stroke-width:1.5px

  classDef frontend fill:#0f766e,stroke:#99f6e4,color:#ecfeff,stroke-width:1.5px
  classDef backend fill:#1d4ed8,stroke:#93c5fd,color:#eff6ff,stroke-width:1.5px
  classDef service fill:#1e40af,stroke:#bfdbfe,color:#eff6ff,stroke-width:1.5px
  classDef adapter fill:#0b4a6f,stroke:#67e8f9,color:#ecfeff,stroke-width:1.5px

  classDef external fill:#7c2d12,stroke:#fdba74,color:#fff7ed,stroke-width:1.5px
  classDef file fill:#064e3b,stroke:#6ee7b7,color:#ecfdf5,stroke-width:1.2px
  classDef dir fill:#065f46,stroke:#34d399,color:#ecfdf5,stroke-width:1.2px
  classDef test fill:#4c1d95,stroke:#c4b5fd,color:#f5f3ff,stroke-width:1.2px
  classDef note fill:#374151,stroke:#d1d5db,color:#f9fafb,stroke-width:1px,stroke-dasharray: 4 3
```
