# bhavika-007/tubelens architecture

> Architecture diagram of the GitHub repository bhavika-007/tubelens, 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/bhavika-007/tubelens
- Repository: https://github.com/bhavika-007/tubelens

## Overview

TubeLens turns a YouTube video into timestamp-aware transcript chunks, then answers video questions with either broad transcript context or locally retrieved passages. The web app adds authenticated video and chat management. The graph reflects the sampled backend orchestration and indexed module references; some retrieval internals and frontend HTTP wiring were not excerpted, so those links are omitted or marked unverified.

Main entry points: [`Backend/routes/chat.py`](https://github.com/bhavika-007/tubelens/blob/main/Backend/routes/chat.py) (Chat routes), [`Backend/routes/video.py`](https://github.com/bhavika-007/tubelens/blob/main/Backend/routes/video.py) (Video routes), [`videoProcessor.py`](https://github.com/bhavika-007/tubelens/blob/main/videoProcessor.py) (Video processing), [`Backend/main.py`](https://github.com/bhavika-007/tubelens/blob/main/Backend/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["App routing<br/>[App.jsx]"]
  node_chatpage["Chat screen<br/>[Chat.jsx]"]
  node_authpages["Login and register<br/>[Login.jsx]"]
  node_api["API client<br/>[api.js]"]
end

subgraph group_service["Backend service"]
  node_backend["FastAPI app<br/>[main.py]"]
  node_authroutes["Authentication routes<br/>[auth.py]"]
  node_videoroutes["Video routes<br/>[video.py]"]
  node_chatroutes["Chat routes<br/>[chat.py]"]
  node_auth["JWT authentication<br/>[auth.py]"]
end

subgraph group_ingest["Transcript ingestion"]
  node_youtube["YouTube utilities<br/>[youtube.py]"]
  node_processor["Video processing<br/>[videoProcessor.py]"]
  node_transcript["Transcript extraction"]
  node_chunker["Timestamped chunks<br/>[chunker.py]"]
  node_embeddings["Embedding generation<br/>[embeddings.py]"]
end

subgraph group_answer["Question answering"]
  node_router["Query routing<br/>[queryRouter.py]"]
  node_rewrite["Follow-up rewriting<br/>[queryRewrite.py]"]
  node_hybrid["Hybrid retrieval<br/>[hybridRetrieval.py]"]
  node_vector["Vector retrieval<br/>[vectorRetrieval.py]"]
  node_bm25["Keyword retrieval<br/>[bm25Retrieval.py]"]
  node_reranker["Passage reranking<br/>[reranker.py]"]
  node_guard["Relevance check<br/>[relevanceGuard.py]"]
  node_llm["Grounded answers<br/>[llm.py]"]
  node_global["Global answers<br/>[globalAnswer.py]"]
  node_timestamp["Timestamp selection<br/>[timestamp.py]"]
end

subgraph group_state["Persistence"]
  node_vectordb[("Vector storage<br/>[vectordb.py]")]
  node_database[("MongoDB collections<br/>[database.py]")]
end

node_user(("Viewer"))
node_groq["Groq LLM service"]
node_youtube_service["YouTube transcript service"]
node_chroma[("ChromaDB")]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_chatpage
node_app -->|"routes to"| node_authpages
node_chatpage -->|"requests"| node_api
node_authpages -->|"requests"| node_api
node_backend -->|"registers"| node_authroutes
node_backend -->|"registers"| node_videoroutes
node_backend -->|"registers"| node_chatroutes
node_authroutes -->|"uses"| node_auth
node_chatroutes -->|"authenticates"| node_auth
node_videoroutes -->|"authenticates"| node_auth
node_auth -->|"reads users"| node_database
node_authroutes -->|"uses"| node_database
node_videoroutes -->|"uses"| node_database
node_chatroutes -->|"reads and writes"| node_database
node_videoroutes -->|"processes video"| node_processor
node_videoroutes -->|"uses"| node_youtube
node_chatroutes -->|"builds watch URL"| node_youtube
node_processor -->|"extracts transcript"| node_transcript
node_processor -->|"creates chunks"| node_chunker
node_processor -->|"embeds chunks"| node_embeddings
node_processor -->|"stores vectors"| node_vectordb
node_transcript -->|"retrieves captions"| node_youtube_service
node_vectordb -.->|"stores in"| node_chroma
node_chatroutes -->|"rewrites query"| node_rewrite
node_chatroutes -->|"classifies query"| node_router
node_chatroutes -->|"answers global query"| node_global
node_chatroutes -->|"retrieves passages"| node_hybrid
node_chatroutes -->|"reranks passages"| node_reranker
node_chatroutes -->|"checks relevance"| node_guard
node_chatroutes -->|"generates answer"| node_llm
node_chatroutes -->|"selects timestamp"| node_timestamp
node_router -->|"classifies with"| node_llm
node_hybrid -->|"combines results"| node_vector
node_hybrid -->|"combines results"| node_bm25
node_global -->|"uses model"| node_llm
node_llm -->|"requests completion"| node_groq
node_api -.->|"calls API"| node_backend

click node_app "https://github.com/bhavika-007/tubelens/blob/main/Frontend/src/App.jsx"
click node_chatpage "https://github.com/bhavika-007/tubelens/blob/main/Frontend/src/pages/Chat.jsx"
click node_authpages "https://github.com/bhavika-007/tubelens/blob/main/Frontend/src/pages/Login.jsx"
click node_api "https://github.com/bhavika-007/tubelens/blob/main/Frontend/src/api/api.js"
click node_backend "https://github.com/bhavika-007/tubelens/blob/main/Backend/main.py"
click node_authroutes "https://github.com/bhavika-007/tubelens/blob/main/Backend/routes/auth.py"
click node_videoroutes "https://github.com/bhavika-007/tubelens/blob/main/Backend/routes/video.py"
click node_chatroutes "https://github.com/bhavika-007/tubelens/blob/main/Backend/routes/chat.py"
click node_auth "https://github.com/bhavika-007/tubelens/blob/main/Backend/utils/auth.py"
click node_youtube "https://github.com/bhavika-007/tubelens/blob/main/Backend/utils/youtube.py"
click node_processor "https://github.com/bhavika-007/tubelens/blob/main/videoProcessor.py"
click node_transcript "https://github.com/bhavika-007/tubelens/blob/main/transcriptExtraction.py"
click node_chunker "https://github.com/bhavika-007/tubelens/blob/main/chunker.py"
click node_embeddings "https://github.com/bhavika-007/tubelens/blob/main/embeddings.py"
click node_vectordb "https://github.com/bhavika-007/tubelens/blob/main/vectordb.py"
click node_router "https://github.com/bhavika-007/tubelens/blob/main/queryRouter.py"
click node_rewrite "https://github.com/bhavika-007/tubelens/blob/main/queryRewrite.py"
click node_hybrid "https://github.com/bhavika-007/tubelens/blob/main/hybridRetrieval.py"
click node_vector "https://github.com/bhavika-007/tubelens/blob/main/vectorRetrieval.py"
click node_bm25 "https://github.com/bhavika-007/tubelens/blob/main/bm25Retrieval.py"
click node_reranker "https://github.com/bhavika-007/tubelens/blob/main/reranker.py"
click node_guard "https://github.com/bhavika-007/tubelens/blob/main/relevanceGuard.py"
click node_llm "https://github.com/bhavika-007/tubelens/blob/main/llm.py"
click node_global "https://github.com/bhavika-007/tubelens/blob/main/globalAnswer.py"
click node_timestamp "https://github.com/bhavika-007/tubelens/blob/main/timestamp.py"
click node_database "https://github.com/bhavika-007/tubelens/blob/main/Backend/database.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_chatpage,node_authpages,node_api,node_user toneBlue
class node_backend,node_authroutes,node_videoroutes,node_chatroutes,node_auth,node_chroma toneAmber
class node_youtube,node_processor,node_transcript,node_chunker,node_embeddings toneMint
class node_router,node_rewrite,node_hybrid,node_vector,node_bm25,node_reranker,node_guard,node_llm,node_global,node_timestamp toneRose
class node_vectordb,node_database,node_groq,node_youtube_service toneIndigo
```

## Components

### Web client

- [App routing](https://github.com/bhavika-007/tubelens/blob/main/Frontend/src/App.jsx): `Frontend/src/App.jsx`
- [Chat screen](https://github.com/bhavika-007/tubelens/blob/main/Frontend/src/pages/Chat.jsx): `Frontend/src/pages/Chat.jsx`
- [Login and register](https://github.com/bhavika-007/tubelens/blob/main/Frontend/src/pages/Login.jsx): `Frontend/src/pages/Login.jsx`
- [API client](https://github.com/bhavika-007/tubelens/blob/main/Frontend/src/api/api.js): `Frontend/src/api/api.js`

### Backend service

- [FastAPI app](https://github.com/bhavika-007/tubelens/blob/main/Backend/main.py): `Backend/main.py`
- [Authentication routes](https://github.com/bhavika-007/tubelens/blob/main/Backend/routes/auth.py): `Backend/routes/auth.py`
- [Video routes](https://github.com/bhavika-007/tubelens/blob/main/Backend/routes/video.py): `Backend/routes/video.py`
- [Chat routes](https://github.com/bhavika-007/tubelens/blob/main/Backend/routes/chat.py): `Backend/routes/chat.py`
- [JWT authentication](https://github.com/bhavika-007/tubelens/blob/main/Backend/utils/auth.py): `Backend/utils/auth.py`

### Transcript ingestion

- [YouTube utilities](https://github.com/bhavika-007/tubelens/blob/main/Backend/utils/youtube.py): `Backend/utils/youtube.py`
- [Video processing](https://github.com/bhavika-007/tubelens/blob/main/videoProcessor.py): `videoProcessor.py`
- [Transcript extraction](https://github.com/bhavika-007/tubelens/blob/main/transcriptExtraction.py): `transcriptExtraction.py`
- [Timestamped chunks](https://github.com/bhavika-007/tubelens/blob/main/chunker.py): `chunker.py`
- [Embedding generation](https://github.com/bhavika-007/tubelens/blob/main/embeddings.py): `embeddings.py`

### Question answering

- [Query routing](https://github.com/bhavika-007/tubelens/blob/main/queryRouter.py): `queryRouter.py`
- [Follow-up rewriting](https://github.com/bhavika-007/tubelens/blob/main/queryRewrite.py): `queryRewrite.py`
- [Hybrid retrieval](https://github.com/bhavika-007/tubelens/blob/main/hybridRetrieval.py): `hybridRetrieval.py`
- [Vector retrieval](https://github.com/bhavika-007/tubelens/blob/main/vectorRetrieval.py): `vectorRetrieval.py`
- [Keyword retrieval](https://github.com/bhavika-007/tubelens/blob/main/bm25Retrieval.py): `bm25Retrieval.py`
- [Passage reranking](https://github.com/bhavika-007/tubelens/blob/main/reranker.py): `reranker.py`
- [Relevance check](https://github.com/bhavika-007/tubelens/blob/main/relevanceGuard.py): `relevanceGuard.py`
- [Grounded answers](https://github.com/bhavika-007/tubelens/blob/main/llm.py): `llm.py`
- [Global answers](https://github.com/bhavika-007/tubelens/blob/main/globalAnswer.py): `globalAnswer.py`
- [Timestamp selection](https://github.com/bhavika-007/tubelens/blob/main/timestamp.py): `timestamp.py`

### Persistence

- [Vector storage](https://github.com/bhavika-007/tubelens/blob/main/vectordb.py): `vectordb.py`
- [MongoDB collections](https://github.com/bhavika-007/tubelens/blob/main/Backend/database.py): `Backend/database.py`

### Other components

- **Viewer**
- **Groq LLM service**
- **YouTube transcript service**
- **ChromaDB**

## Connections

- Viewer → App routing: uses (evidence: `Frontend/src/App.jsx`)
- App routing → Chat screen: routes to (evidence: `Frontend/src/App.jsx`)
- App routing → Login and register: routes to (evidence: `Frontend/src/App.jsx`)
- Chat screen → API client: requests (evidence: `Frontend/src/pages/Chat.jsx`)
- Login and register → API client: requests (evidence: `Frontend/src/pages/Login.jsx`)
- FastAPI app → Authentication routes: registers (evidence: `Backend/main.py`)
- FastAPI app → Video routes: registers (evidence: `Backend/main.py`)
- FastAPI app → Chat routes: registers (evidence: `Backend/main.py`)
- Authentication routes → JWT authentication: uses (evidence: `Backend/routes/auth.py`)
- Chat routes → JWT authentication: authenticates (evidence: `Backend/routes/chat.py`)
- Video routes → JWT authentication: authenticates (evidence: `Backend/routes/video.py`)
- JWT authentication → MongoDB collections: reads users (evidence: `Backend/utils/auth.py`)
- Authentication routes → MongoDB collections: uses (evidence: `Backend/routes/auth.py`)
- Video routes → MongoDB collections: uses (evidence: `Backend/routes/video.py`)
- Chat routes → MongoDB collections: reads and writes (evidence: `Backend/routes/chat.py`)
- Video routes → Video processing: processes video (evidence: `Backend/routes/video.py`)
- Video routes → YouTube utilities: uses (evidence: `Backend/routes/video.py`)
- Chat routes → YouTube utilities: builds watch URL (evidence: `Backend/routes/chat.py`)
- Video processing → Transcript extraction: extracts transcript (evidence: `videoProcessor.py`)
- Video processing → Timestamped chunks: creates chunks (evidence: `videoProcessor.py`)
- Video processing → Embedding generation: embeds chunks (evidence: `videoProcessor.py`)
- Video processing → Vector storage: stores vectors (evidence: `videoProcessor.py`)
- Transcript extraction → YouTube transcript service: retrieves captions (evidence: `transcriptExtraction.py`)
- Vector storage → ChromaDB: stores in
- Chat routes → Follow-up rewriting: rewrites query (evidence: `Backend/routes/chat.py`)
- Chat routes → Query routing: classifies query (evidence: `Backend/routes/chat.py`)
- Chat routes → Global answers: answers global query (evidence: `Backend/routes/chat.py`)
- Chat routes → Hybrid retrieval: retrieves passages (evidence: `Backend/routes/chat.py`)
- Chat routes → Passage reranking: reranks passages (evidence: `Backend/routes/chat.py`)
- Chat routes → Relevance check: checks relevance (evidence: `Backend/routes/chat.py`)
- Chat routes → Grounded answers: generates answer (evidence: `Backend/routes/chat.py`)
- Chat routes → Timestamp selection: selects timestamp (evidence: `Backend/routes/chat.py`)
- Query routing → Grounded answers: classifies with (evidence: `queryRouter.py`)
- Hybrid retrieval → Vector retrieval: combines results (evidence: `hybridRetrieval.py`)
- Hybrid retrieval → Keyword retrieval: combines results (evidence: `hybridRetrieval.py`)
- Global answers → Grounded answers: uses model (evidence: `globalAnswer.py`)
- Grounded answers → Groq LLM service: requests completion (evidence: `llm.py`)
- API client → FastAPI app: calls API
