# sreekar-2612/youtube-sage architecture

> Architecture diagram of the GitHub repository sreekar-2612/youtube-sage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sreekar-2612/youtube-sage
- Repository: https://github.com/sreekar-2612/youtube-sage

## Overview

YT-Sage is a YouTube-transcript chat application. A user selects a model and submits a video URL; the frontend calls the FastAPI service, which loads and chunks the transcript, builds a retriever, and creates a session. Chat requests then use either conversational retrieval or agent mode, with session history maintained in memory. The frontend renders answers and session controls. The graph follows the shown endpoint wiring and module references; optional transcript fallbacks are shown separately, and unsampled agent internals are not inferred.

Main entry points: [`backend/main.py`](https://github.com/sreekar-2612/youtube-sage/blob/main/backend/main.py) (Session API), [`frontend/src/App.jsx`](https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/App.jsx) (Application state), [`frontend/src/components/ChatPanel.jsx`](https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/components/ChatPanel.jsx) (Chat panel), [`backend/src/chains.py`](https://github.com/sreekar-2612/youtube-sage/blob/main/backend/src/chains.py) (Conversational RAG)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_app["Application state<br/>[App.jsx]"]
  node_source_ui["Video source<br/>[Sidebar.jsx]"]
  node_engine_ui["Engine controls<br/>[EngineConfig.jsx]"]
  node_chat_ui["Chat panel<br/>[ChatPanel.jsx]"]
  node_message_card["Message card<br/>[MessageCard.jsx]"]
  node_turn_divider["Turn divider<br/>[TurnDivider.jsx]"]
  node_http_client["HTTP client<br/>[api.js]"]
end

subgraph group_api["API and sessions"]
  node_fastapi["Session API<br/>[main.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_ingest["Transcript indexing"]
  node_transcript["Transcript loader<br/>[youtube_loader.py]"]
  node_chunker["Text chunking<br/>[text_processing.py]"]
  node_vectorstore[("Vector retrieval<br/>[vectorstore.py]")]
end

subgraph group_answer["Answer generation"]
  node_model_setup["Model provider<br/>[llm_setup.py]"]
  node_rag_chain["Conversational RAG<br/>[chains.py]"]
  node_agent_tools["Agent tools<br/>[agent_tools.py]"]
end

node_user(("User"))
node_transcript_service(("Transcript services"))
node_model_services(("Model APIs"))

node_user -->|"interacts"| node_app
node_app -->|"renders"| node_source_ui
node_app -->|"renders"| node_engine_ui
node_app -->|"renders"| node_chat_ui
node_app -->|"requests"| node_http_client
node_chat_ui -->|"renders"| node_message_card
node_chat_ui -->|"renders"| node_turn_divider
node_http_client -->|"HTTP requests"| node_fastapi
node_fastapi -->|"reads settings"| node_config
node_fastapi -->|"loads transcript"| node_transcript
node_fastapi -->|"splits documents"| node_chunker
node_fastapi -->|"builds retriever"| node_vectorstore
node_fastapi -->|"selects model"| node_model_setup
node_fastapi -->|"builds and invokes"| node_rag_chain
node_fastapi -->|"builds agent"| node_agent_tools
node_rag_chain -->|"retrieves context"| node_vectorstore
node_fastapi -->|"stores chat history"| node_rag_chain
node_transcript -.->|"fallback fetch"| node_transcript_service
node_model_setup -.->|"inference"| node_model_services

click node_app "https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/App.jsx"
click node_source_ui "https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/components/Sidebar.jsx"
click node_engine_ui "https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/components/EngineConfig.jsx"
click node_chat_ui "https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/components/ChatPanel.jsx"
click node_message_card "https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/components/MessageCard.jsx"
click node_turn_divider "https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/components/TurnDivider.jsx"
click node_http_client "https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/api.js"
click node_fastapi "https://github.com/sreekar-2612/youtube-sage/blob/main/backend/main.py"
click node_transcript "https://github.com/sreekar-2612/youtube-sage/blob/main/backend/src/youtube_loader.py"
click node_chunker "https://github.com/sreekar-2612/youtube-sage/blob/main/backend/src/text_processing.py"
click node_vectorstore "https://github.com/sreekar-2612/youtube-sage/blob/main/backend/src/vectorstore.py"
click node_model_setup "https://github.com/sreekar-2612/youtube-sage/blob/main/backend/src/llm_setup.py"
click node_rag_chain "https://github.com/sreekar-2612/youtube-sage/blob/main/backend/src/chains.py"
click node_agent_tools "https://github.com/sreekar-2612/youtube-sage/blob/main/backend/src/agent_tools.py"
click node_config "https://github.com/sreekar-2612/youtube-sage/blob/main/backend/src/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_source_ui,node_engine_ui,node_chat_ui,node_message_card,node_turn_divider,node_http_client,node_user toneBlue
class node_fastapi,node_config toneAmber
class node_transcript,node_chunker,node_vectorstore,node_model_services toneMint
class node_model_setup,node_rag_chain,node_agent_tools toneRose
class node_transcript_service toneIndigo
```

## Components

### Web interface

- [Application state](https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Video source](https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/components/Sidebar.jsx): `frontend/src/components/Sidebar.jsx`
- [Engine controls](https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/components/EngineConfig.jsx): `frontend/src/components/EngineConfig.jsx`
- [Chat panel](https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/components/ChatPanel.jsx): `frontend/src/components/ChatPanel.jsx`
- [Message card](https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/components/MessageCard.jsx): `frontend/src/components/MessageCard.jsx`
- [Turn divider](https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/components/TurnDivider.jsx): `frontend/src/components/TurnDivider.jsx`
- [HTTP client](https://github.com/sreekar-2612/youtube-sage/blob/main/frontend/src/api.js): `frontend/src/api.js`

### API and sessions

- [Session API](https://github.com/sreekar-2612/youtube-sage/blob/main/backend/main.py): `backend/main.py`
- [Runtime configuration](https://github.com/sreekar-2612/youtube-sage/blob/main/backend/src/config.py): `backend/src/config.py`

### Transcript indexing

- [Transcript loader](https://github.com/sreekar-2612/youtube-sage/blob/main/backend/src/youtube_loader.py): `backend/src/youtube_loader.py`
- [Text chunking](https://github.com/sreekar-2612/youtube-sage/blob/main/backend/src/text_processing.py): `backend/src/text_processing.py`
- [Vector retrieval](https://github.com/sreekar-2612/youtube-sage/blob/main/backend/src/vectorstore.py): `backend/src/vectorstore.py`

### Answer generation

- [Model provider](https://github.com/sreekar-2612/youtube-sage/blob/main/backend/src/llm_setup.py): `backend/src/llm_setup.py`
- [Conversational RAG](https://github.com/sreekar-2612/youtube-sage/blob/main/backend/src/chains.py): `backend/src/chains.py`
- [Agent tools](https://github.com/sreekar-2612/youtube-sage/blob/main/backend/src/agent_tools.py): `backend/src/agent_tools.py`

### Other components

- **User**
- **Transcript services**
- **Model APIs**

## Connections

- User → Application state: interacts (evidence: `frontend/src/App.jsx`)
- Application state → Video source: renders (evidence: `frontend/src/App.jsx`)
- Application state → Engine controls: renders (evidence: `frontend/src/App.jsx`)
- Application state → Chat panel: renders (evidence: `frontend/src/App.jsx`)
- Application state → HTTP client: requests (evidence: `frontend/src/App.jsx`)
- Chat panel → Message card: renders (evidence: `frontend/src/components/ChatPanel.jsx`)
- Chat panel → Turn divider: renders (evidence: `frontend/src/components/ChatPanel.jsx`)
- HTTP client → Session API: HTTP requests (evidence: `frontend/src/api.js`)
- Session API → Runtime configuration: reads settings (evidence: `backend/main.py`)
- Session API → Transcript loader: loads transcript (evidence: `backend/main.py`)
- Session API → Text chunking: splits documents (evidence: `backend/main.py`)
- Session API → Vector retrieval: builds retriever (evidence: `backend/main.py`)
- Session API → Model provider: selects model (evidence: `backend/main.py`)
- Session API → Conversational RAG: builds and invokes (evidence: `backend/main.py`)
- Session API → Agent tools: builds agent (evidence: `backend/main.py`)
- Conversational RAG → Vector retrieval: retrieves context (evidence: `backend/src/chains.py`)
- Session API → Conversational RAG: stores chat history (evidence: `backend/main.py`)
- Transcript loader → Transcript services: fallback fetch (evidence: `backend/src/youtube_loader.py`)
- Model provider → Model APIs: inference (evidence: `backend/src/llm_setup.py`)
