# vijayyy-code/youtube_qna_system architecture

> Architecture diagram of the GitHub repository vijayyy-code/youtube_qna_system, 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/vijayyy-code/youtube_qna_system
- Repository: https://github.com/vijayyy-code/youtube_qna_system

## Overview

YouTube Video Q&A is a Streamlit-based, captions-first transcript assistant with Whisper transcription fallback, semantic retrieval, and Groq-generated answers. The main workflow is to process a video, clean and chunk its transcript, optionally add a generated summary, build an in-session FAISS index, then retrieve context and answer questions across chat turns. Speaker questions can instead use video metadata. The source excerpts show the main call paths; external service links reflect calls visible in source, while documented capabilities such as optional retrieval-detail display are retained.

Main entry points: [`src/ui.py`](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/ui.py) (Chat UI), [`src/ingest.py`](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/ingest.py) (Video ingestion), [`src/indexing.py`](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/indexing.py) (Vector indexing), [`src/qa.py`](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/qa.py) (Chunk reranking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Chat interaction"]
  node_app["App entry<br/>[app.py]"]
  node_chat_ui["Chat UI<br/>[ui.py]"]
end

subgraph group_ingestion["Video ingestion"]
  node_video_ingestion["Video ingestion<br/>[ingest.py]"]
  node_caption_fetch["Caption fetch<br/>[ingest.py]"]
  node_audio_fetch["Audio fetch<br/>[ingest.py]"]
  node_metadata["Video metadata<br/>[ingest.py]"]
end

subgraph group_transcript["Transcript processing"]
  node_transcript_cleanup["Transcript cleanup<br/>[transcript.py]"]
  node_chunking["Transcript chunking<br/>[transcript.py]"]
end

subgraph group_retrieval["Retrieval and state"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_indexing["Vector indexing<br/>[indexing.py]"]
  node_vector_store[("FAISS vector store<br/>[state.py]")]
  node_retrieval_qa["Chunk reranking<br/>[qa.py]"]
  node_chat_state["Session state<br/>[ui.py]"]
end

subgraph group_answers["Answer generation"]
  node_whisper["Whisper transcription<br/>[llm.py]"]
  node_summary["Transcript summary<br/>[llm.py]"]
  node_answering["Grounded answering<br/>[llm.py]"]
end

node_user(("Viewer"))
node_video_source(("YouTube video"))
node_groq{{"Groq API"}}

node_user -->|"uses"| node_chat_ui
node_app -->|"runs"| node_chat_ui
node_chat_ui -->|"processes video"| node_video_ingestion
node_video_ingestion -->|"fetches metadata"| node_video_source
node_video_ingestion -->|"tries captions"| node_caption_fetch
node_video_ingestion -->|"fallback downloads"| node_audio_fetch
node_video_ingestion -->|"extracts"| node_metadata
node_video_ingestion -->|"parses captions"| node_transcript_cleanup
node_video_ingestion -->|"transcribes fallback"| node_whisper
node_whisper -->|"calls transcription"| node_groq
node_chat_ui -->|"chunks transcript"| node_chunking
node_chat_ui -->|"requests summary"| node_summary
node_summary -->|"generates summary"| node_groq
node_chat_ui -->|"builds index"| node_indexing
node_indexing -->|"creates index"| node_vector_store
node_chat_ui -->|"gets relevant chunks"| node_retrieval_qa
node_retrieval_qa -->|"retrieves candidates"| node_indexing
node_chat_ui -->|"submits question"| node_answering
node_answering -->|"generates answer"| node_groq
node_chat_ui -->|"answers speaker questions"| node_metadata
node_chat_ui -->|"stores chat turns"| node_chat_state
node_chat_ui -->|"loads settings"| node_settings
node_chat_ui -->|"shows retrieval details"| node_chat_state

click node_app "https://github.com/vijayyy-code/youtube_qna_system/blob/main/app.py"
click node_chat_ui "https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/ui.py"
click node_video_ingestion "https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/ingest.py"
click node_caption_fetch "https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/ingest.py"
click node_audio_fetch "https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/ingest.py"
click node_metadata "https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/ingest.py"
click node_transcript_cleanup "https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/transcript.py"
click node_chunking "https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/transcript.py"
click node_settings "https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/config.py"
click node_indexing "https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/indexing.py"
click node_vector_store "https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/state.py"
click node_retrieval_qa "https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/qa.py"
click node_chat_state "https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/ui.py"
click node_whisper "https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/llm.py"
click node_summary "https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/llm.py"
click node_answering "https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/llm.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_chat_ui,node_user toneBlue
class node_video_ingestion,node_caption_fetch,node_audio_fetch,node_metadata toneAmber
class node_transcript_cleanup,node_chunking,node_groq toneMint
class node_settings,node_indexing,node_vector_store,node_retrieval_qa,node_chat_state toneRose
class node_whisper,node_summary,node_answering,node_video_source toneIndigo
```

## Components

### Chat interaction

- [App entry](https://github.com/vijayyy-code/youtube_qna_system/blob/main/app.py): `app.py`
- [Chat UI](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/ui.py): `src/ui.py`

### Video ingestion

- [Video ingestion](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/ingest.py): `src/ingest.py`
- [Caption fetch](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/ingest.py): `src/ingest.py`
- [Audio fetch](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/ingest.py): `src/ingest.py`
- [Video metadata](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/ingest.py): `src/ingest.py`

### Transcript processing

- [Transcript cleanup](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/transcript.py): `src/transcript.py`
- [Transcript chunking](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/transcript.py): `src/transcript.py`

### Retrieval and state

- [Runtime settings](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/config.py): `src/config.py`
- [Vector indexing](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/indexing.py): `src/indexing.py`
- [FAISS vector store](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/state.py): `src/state.py`
- [Chunk reranking](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/qa.py): `src/qa.py`
- [Session state](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/ui.py): `src/ui.py`

### Answer generation

- [Whisper transcription](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/llm.py): `src/llm.py`
- [Transcript summary](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/llm.py): `src/llm.py`
- [Grounded answering](https://github.com/vijayyy-code/youtube_qna_system/blob/main/src/llm.py): `src/llm.py`

### Other components

- **Viewer**
- **YouTube video**
- **Groq API**

## Connections

- Viewer → Chat UI: uses (evidence: `src/ui.py`)
- App entry → Chat UI: runs (evidence: `app.py`)
- Chat UI → Video ingestion: processes video (evidence: `src/ui.py`)
- Video ingestion → YouTube video: fetches metadata (evidence: `src/ingest.py`)
- Video ingestion → Caption fetch: tries captions (evidence: `src/ingest.py`)
- Video ingestion → Audio fetch: fallback downloads (evidence: `src/ingest.py`)
- Video ingestion → Video metadata: extracts (evidence: `src/ingest.py`)
- Video ingestion → Transcript cleanup: parses captions (evidence: `src/ingest.py`)
- Video ingestion → Whisper transcription: transcribes fallback (evidence: `src/ingest.py`)
- Whisper transcription → Groq API: calls transcription (evidence: `src/llm.py`)
- Chat UI → Transcript chunking: chunks transcript (evidence: `src/ui.py`)
- Chat UI → Transcript summary: requests summary (evidence: `src/ui.py`)
- Transcript summary → Groq API: generates summary (evidence: `src/llm.py`)
- Chat UI → Vector indexing: builds index (evidence: `src/ui.py`)
- Vector indexing → FAISS vector store: creates index (evidence: `src/indexing.py`)
- Chat UI → Chunk reranking: gets relevant chunks (evidence: `src/ui.py`)
- Chunk reranking → Vector indexing: retrieves candidates (evidence: `src/qa.py`)
- Chat UI → Grounded answering: submits question (evidence: `src/ui.py`)
- Grounded answering → Groq API: generates answer (evidence: `src/llm.py`)
- Chat UI → Video metadata: answers speaker questions (evidence: `src/ui.py`)
- Chat UI → Session state: stores chat turns (evidence: `src/ui.py`)
- Chat UI → Runtime settings: loads settings (evidence: `src/ui.py`)
- Chat UI → Session state: shows retrieval details (evidence: `src/ui.py`)
