# profgaurav/advanced-rag-experimentation architecture

> Architecture diagram of the GitHub repository profgaurav/advanced-rag-experimentation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/profgaurav/advanced-rag-experimentation
- Repository: https://github.com/profgaurav/advanced-rag-experimentation

## Overview

YouTube RAG has a one-time backend indexing workflow and a separate Streamlit question-answering workflow. Indexing fetches a transcript, chunks it, embeds it, and persists a FAISS index; the UI loads that index, retrieves relevant chunks, and asks an LLM to answer. The graph preserves the documented prompt, chain, and configuration layers. Some chain internals and the CLI implementation are unsampled, so those relationships rely on the README; no other unsampled source behavior is inferred.

Main entry points: [`src/yt_rag/qa.py`](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/qa.py) (QA service), [`src/yt_rag/indexing.py`](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/indexing.py) (Index builder), [`src/yt_rag/vectorstore/faiss_store.py`](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/vectorstore/faiss_store.py) (FAISS store), [`app.py`](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/app.py) (Streamlit entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_indexing["Indexing"]
  node_cli["Index CLI<br/>[build_index.py]"]
  node_settings["Settings<br/>[config.py]"]
  node_transcript["Transcript fetch<br/>[transcript.py]"]
  node_splitter["Transcript chunker<br/>[splitter.py]"]
  node_indexing_service["Index builder<br/>[indexing.py]"]
end

subgraph group_storage["Vector storage"]
  node_embedding["Embedding factory<br/>[embeddings.py]"]
  node_faiss["FAISS store<br/>[faiss_store.py]"]
  node_index_data[("Persisted index")]
end

subgraph group_answering["Answering"]
  node_qa_service["QA service<br/>[qa.py]"]
  node_retriever["Retriever<br/>[retriever.py]"]
  node_prompt["QA prompt<br/>[prompts.py]"]
  node_llm["Chat model<br/>[llm.py]"]
  node_chain["QA chain<br/>[qa_chain.py]"]
  node_errors["Domain errors<br/>[exceptions.py]"]
end

subgraph group_interface["Chat interface"]
  node_app["Streamlit entry<br/>[app.py]"]
  node_chat_ui["Chat UI<br/>[chat.py]"]
end

node_operator(("Video ID provider"))
node_youtube["YouTube transcripts"]
node_openai["OpenAI models"]
node_user(("Question asker"))

node_operator -->|"provides video ID"| node_cli
node_cli -->|"runs indexing"| node_indexing_service
node_indexing_service -->|"reads settings"| node_settings
node_indexing_service -->|"fetches transcript"| node_transcript
node_transcript -->|"fetches captions"| node_youtube
node_indexing_service -->|"chunks transcript"| node_splitter
node_indexing_service -->|"gets embeddings"| node_embedding
node_embedding -->|"creates embeddings"| node_openai
node_indexing_service -->|"builds and saves"| node_faiss
node_faiss -->|"persists index"| node_index_data
node_user -->|"enters question"| node_chat_ui
node_app -->|"renders chat"| node_chat_ui
node_app -->|"loads chain and answers"| node_qa_service
node_qa_service -->|"reads settings"| node_settings
node_qa_service -->|"loads index"| node_faiss
node_faiss -->|"reads index"| node_index_data
node_qa_service -->|"gets embeddings"| node_embedding
node_qa_service -->|"builds retriever"| node_retriever
node_qa_service -->|"gets prompt"| node_prompt
node_qa_service -->|"gets chat model"| node_llm
node_qa_service -->|"builds QA chain"| node_chain
node_qa_service -.->|"retrieves chunks"| node_retriever
node_qa_service -.->|"formats context"| node_prompt
node_qa_service -.->|"generates answer"| node_llm
node_app -->|"handles missing index"| node_errors

click node_cli "https://github.com/profgaurav/advanced-rag-experimentation/blob/main/scripts/build_index.py"
click node_settings "https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/config.py"
click node_transcript "https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/ingestion/transcript.py"
click node_splitter "https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/ingestion/splitter.py"
click node_embedding "https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/vectorstore/embeddings.py"
click node_indexing_service "https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/indexing.py"
click node_faiss "https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/vectorstore/faiss_store.py"
click node_index_data "https://github.com/profgaurav/advanced-rag-experimentation/tree/main/data/vectorstore"
click node_app "https://github.com/profgaurav/advanced-rag-experimentation/blob/main/app.py"
click node_chat_ui "https://github.com/profgaurav/advanced-rag-experimentation/blob/main/ui/chat.py"
click node_qa_service "https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/qa.py"
click node_retriever "https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/chains/retriever.py"
click node_prompt "https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/chains/prompts.py"
click node_llm "https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/chains/llm.py"
click node_chain "https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/chains/qa_chain.py"
click node_errors "https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/exceptions.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_cli,node_settings,node_transcript,node_splitter,node_indexing_service toneBlue
class node_embedding,node_faiss,node_index_data toneAmber
class node_qa_service,node_retriever,node_prompt,node_llm,node_chain,node_errors toneMint
class node_app,node_chat_ui toneRose
class node_operator,node_youtube,node_openai,node_user toneIndigo
```

## Components

### Indexing

- [Index CLI](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/scripts/build_index.py): `scripts/build_index.py`
- [Settings](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/config.py): `src/yt_rag/config.py`
- [Transcript fetch](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/ingestion/transcript.py): `src/yt_rag/ingestion/transcript.py`
- [Transcript chunker](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/ingestion/splitter.py): `src/yt_rag/ingestion/splitter.py`
- [Index builder](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/indexing.py): `src/yt_rag/indexing.py`

### Vector storage

- [Embedding factory](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/vectorstore/embeddings.py): `src/yt_rag/vectorstore/embeddings.py`
- [FAISS store](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/vectorstore/faiss_store.py): `src/yt_rag/vectorstore/faiss_store.py`
- [Persisted index](https://github.com/profgaurav/advanced-rag-experimentation/tree/main/data/vectorstore): `data/vectorstore`

### Answering

- [QA service](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/qa.py): `src/yt_rag/qa.py`
- [Retriever](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/chains/retriever.py): `src/yt_rag/chains/retriever.py`
- [QA prompt](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/chains/prompts.py): `src/yt_rag/chains/prompts.py`
- [Chat model](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/chains/llm.py): `src/yt_rag/chains/llm.py`
- [QA chain](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/chains/qa_chain.py): `src/yt_rag/chains/qa_chain.py`
- [Domain errors](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/src/yt_rag/exceptions.py): `src/yt_rag/exceptions.py`

### Chat interface

- [Streamlit entry](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/app.py): `app.py`
- [Chat UI](https://github.com/profgaurav/advanced-rag-experimentation/blob/main/ui/chat.py): `ui/chat.py`

### Other components

- **Video ID provider**
- **YouTube transcripts**
- **OpenAI models**
- **Question asker**

## Connections

- Video ID provider → Index CLI: provides video ID (evidence: `README.md`)
- Index CLI → Index builder: runs indexing (evidence: `README.md`)
- Index builder → Settings: reads settings (evidence: `src/yt_rag/indexing.py`)
- Index builder → Transcript fetch: fetches transcript (evidence: `src/yt_rag/indexing.py`)
- Transcript fetch → YouTube transcripts: fetches captions (evidence: `src/yt_rag/ingestion/transcript.py`)
- Index builder → Transcript chunker: chunks transcript (evidence: `src/yt_rag/indexing.py`)
- Index builder → Embedding factory: gets embeddings (evidence: `src/yt_rag/indexing.py`)
- Embedding factory → OpenAI models: creates embeddings (evidence: `README.md`)
- Index builder → FAISS store: builds and saves (evidence: `src/yt_rag/indexing.py`)
- FAISS store → Persisted index: persists index (evidence: `README.md`)
- Question asker → Chat UI: enters question (evidence: `README.md`)
- Streamlit entry → Chat UI: renders chat (evidence: `app.py`)
- Streamlit entry → QA service: loads chain and answers (evidence: `app.py`)
- QA service → Settings: reads settings (evidence: `src/yt_rag/qa.py`)
- QA service → FAISS store: loads index (evidence: `src/yt_rag/qa.py`)
- FAISS store → Persisted index: reads index (evidence: `README.md`)
- QA service → Embedding factory: gets embeddings (evidence: `src/yt_rag/qa.py`)
- QA service → Retriever: builds retriever (evidence: `src/yt_rag/qa.py`)
- QA service → QA prompt: gets prompt (evidence: `src/yt_rag/qa.py`)
- QA service → Chat model: gets chat model (evidence: `src/yt_rag/qa.py`)
- QA service → QA chain: builds QA chain (evidence: `src/yt_rag/qa.py`)
- QA service → Retriever: retrieves chunks (evidence: `README.md`)
- QA service → QA prompt: formats context (evidence: `README.md`)
- QA service → Chat model: generates answer (evidence: `README.md`)
- Streamlit entry → Domain errors: handles missing index (evidence: `app.py`)