# garvitsh003/bhajan-marg-ai architecture

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

- Interactive diagram: https://gitdiagram.com/garvitsh003/bhajan-marg-ai
- Repository: https://github.com/garvitsh003/bhajan-marg-ai

## Overview

Bhajan Marg AI is a transcript-grounded devotional chatbot with a growing YouTube corpus. Its main workflow serves a chat request, uses conversation history to rewrite the question, searches and judges fresh transcript evidence, then returns an explanation with timestamped source cards. A separate ingestion workflow discovers videos, obtains transcripts, chunks and indexes them, while SQLite tracks corpus and conversation state. The README also documents optional cloud providers and periodic LoRA style training. Some subsystem links are omitted where the sampled excerpts do not show the runtime call.

Main entry points: [`app/llm.py`](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/llm.py) (Query and LLM), [`app/main.py`](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/main.py) (Chat API), [`app/ingest.py`](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/ingest.py) (Ingestion workflow), [`app/retrieval.py`](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/retrieval.py) (Evidence retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chat["Chat and answers"]
  node_webui["Chat interface<br/>[app.js]"]
  node_api["Chat API<br/>[main.py]"]
  node_llm["Query and LLM<br/>[llm.py]"]
  node_policy["Answer policy<br/>[answer_policy.py]"]
  node_synthesis["Answer synthesis<br/>[synthesis.py]"]
end

subgraph group_search["Retrieval and indexing"]
  node_retrieval["Evidence retrieval<br/>[retrieval.py]"]
  node_searchbackend["Search dispatch<br/>[search_backend.py]"]
  node_localvectors["Local hybrid search<br/>[vector_store.py]"]
  node_cloudvectors["Cloud hybrid search"]
  node_text["Text processing<br/>[text.py]"]
end

subgraph group_corpus["Corpus ingestion"]
  node_chunking["Transcript chunking<br/>[chunking.py]"]
  node_ingest["Ingestion workflow<br/>[ingest.py]"]
  node_youtube["Video transcripts<br/>[youtube.py]"]
  node_scheduler["Daily updater<br/>[scheduler.py]"]
end

subgraph group_services["Storage and providers"]
  node_sqlite[("Corpus and chat DB<br/>[db.py]")]
  node_qdrant[("Qdrant vector store")]
  node_ollama["Ollama service"]
  node_gemini["Gemini service"]
  node_cloudllm["Gemini adapter<br/>[cloud_llm.py]"]
  node_budget["Request deadlines<br/>[budget.py]"]
end

subgraph group_learning["Optional style learning"]
  node_styledata["Style dataset builder"]
  node_loratraining["LoRA training<br/>[train_lora.py]"]
end

node_visitor(("Chat user"))
node_youtube_service["YouTube"]

node_visitor -->|"uses"| node_webui
node_api -->|"serves"| node_webui
node_api -->|"loads and saves"| node_sqlite
node_api -->|"rewrites query"| node_llm
node_api -->|"requests evidence"| node_retrieval
node_api -.->|"starts scheduler"| node_scheduler
node_api -->|"queues update"| node_ingest
node_llm -->|"uses policy"| node_policy
node_llm -->|"sends chat"| node_ollama
node_llm -->|"delegates cloud calls"| node_cloudllm
node_cloudllm -->|"sends prompts"| node_gemini
node_llm -->|"checks deadlines"| node_budget
node_retrieval -->|"searches and reranks"| node_searchbackend
node_retrieval -->|"judges evidence"| node_llm
node_retrieval -->|"loads context"| node_sqlite
node_searchbackend -->|"dispatches local"| node_localvectors
node_searchbackend -->|"dispatches cloud"| node_cloudvectors
node_localvectors -->|"queries and indexes"| node_qdrant
node_localvectors -->|"builds lexical vectors"| node_text
node_cloudvectors -->|"queries cloud index"| node_qdrant
node_ingest -->|"gets video transcripts"| node_youtube
node_ingest -->|"chunks transcript"| node_chunking
node_chunking -->|"normalizes text"| node_text
node_ingest -->|"records corpus state"| node_sqlite
node_ingest -->|"indexes chunks"| node_localvectors
node_youtube -.->|"retrieves videos"| node_youtube_service
node_scheduler -->|"runs updates"| node_ingest
node_styledata -->|"reads corpus"| node_sqlite
node_styledata -->|"builds examples"| node_llm
node_styledata -.->|"provides reviewed data"| node_loratraining
node_synthesis -->|"uses provider"| node_cloudllm
node_synthesis -->|"uses search backend"| node_searchbackend

click node_webui "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/static/app.js"
click node_api "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/main.py"
click node_llm "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/llm.py"
click node_policy "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/answer_policy.py"
click node_synthesis "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/synthesis.py"
click node_retrieval "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/retrieval.py"
click node_searchbackend "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/search_backend.py"
click node_localvectors "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/vector_store.py"
click node_cloudvectors "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/cloud_vector_store.py"
click node_text "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/text.py"
click node_chunking "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/chunking.py"
click node_ingest "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/ingest.py"
click node_youtube "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/youtube.py"
click node_scheduler "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/scheduler.py"
click node_sqlite "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/db.py"
click node_cloudllm "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/cloud_llm.py"
click node_budget "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/budget.py"
click node_styledata "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/training/build_style_dataset.py"
click node_loratraining "https://github.com/garvitsh003/bhajan-marg-ai/blob/main/training/train_lora.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_webui,node_api,node_llm,node_policy,node_synthesis,node_visitor toneBlue
class node_retrieval,node_searchbackend,node_localvectors,node_cloudvectors,node_text toneAmber
class node_chunking,node_ingest,node_youtube,node_scheduler toneMint
class node_sqlite,node_qdrant,node_ollama,node_gemini,node_cloudllm,node_budget toneRose
class node_styledata,node_loratraining,node_youtube_service toneIndigo
```

## Components

### Chat and answers

- [Chat interface](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/static/app.js): `app/static/app.js`
- [Chat API](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/main.py): `app/main.py`
- [Query and LLM](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/llm.py): `app/llm.py`
- [Answer policy](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/answer_policy.py): `app/answer_policy.py`
- [Answer synthesis](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/synthesis.py): `app/synthesis.py`

### Retrieval and indexing

- [Evidence retrieval](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/retrieval.py): `app/retrieval.py`
- [Search dispatch](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/search_backend.py): `app/search_backend.py`
- [Local hybrid search](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/vector_store.py): `app/vector_store.py`
- [Cloud hybrid search](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/cloud_vector_store.py): `app/cloud_vector_store.py`
- [Text processing](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/text.py): `app/text.py`

### Corpus ingestion

- [Transcript chunking](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/chunking.py): `app/chunking.py`
- [Ingestion workflow](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/ingest.py): `app/ingest.py`
- [Video transcripts](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/youtube.py): `app/youtube.py`
- [Daily updater](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/scheduler.py): `app/scheduler.py`

### Storage and providers

- [Corpus and chat DB](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/db.py): `app/db.py`
- **Qdrant vector store**
- **Ollama service**
- **Gemini service**
- [Gemini adapter](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/cloud_llm.py): `app/cloud_llm.py`
- [Request deadlines](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/app/budget.py): `app/budget.py`

### Optional style learning

- [Style dataset builder](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/training/build_style_dataset.py): `training/build_style_dataset.py`
- [LoRA training](https://github.com/garvitsh003/bhajan-marg-ai/blob/main/training/train_lora.py): `training/train_lora.py`

### Other components

- **Chat user**
- **YouTube**

## Connections

- Chat user → Chat interface: uses (evidence: `README.md`)
- Chat API → Chat interface: serves (evidence: `app/main.py`)
- Chat API → Corpus and chat DB: loads and saves (evidence: `app/main.py`)
- Chat API → Query and LLM: rewrites query (evidence: `app/main.py`)
- Chat API → Evidence retrieval: requests evidence (evidence: `app/main.py`)
- Chat API → Daily updater: starts scheduler (evidence: `app/main.py`)
- Chat API → Ingestion workflow: queues update (evidence: `app/main.py`)
- Query and LLM → Answer policy: uses policy (evidence: `app/answer_policy.py`)
- Query and LLM → Ollama service: sends chat (evidence: `app/llm.py`)
- Query and LLM → Gemini adapter: delegates cloud calls (evidence: `app/llm.py`)
- Gemini adapter → Gemini service: sends prompts (evidence: `app/cloud_llm.py`)
- Query and LLM → Request deadlines: checks deadlines (evidence: `app/llm.py`)
- Evidence retrieval → Search dispatch: searches and reranks (evidence: `app/retrieval.py`)
- Evidence retrieval → Query and LLM: judges evidence (evidence: `app/retrieval.py`)
- Evidence retrieval → Corpus and chat DB: loads context (evidence: `app/retrieval.py`)
- Search dispatch → Local hybrid search: dispatches local (evidence: `app/search_backend.py`)
- Search dispatch → Cloud hybrid search: dispatches cloud (evidence: `app/search_backend.py`)
- Local hybrid search → Qdrant vector store: queries and indexes (evidence: `app/vector_store.py`)
- Local hybrid search → Text processing: builds lexical vectors (evidence: `app/vector_store.py`)
- Cloud hybrid search → Qdrant vector store: queries cloud index (evidence: `app/cloud_vector_store.py`)
- Ingestion workflow → Video transcripts: gets video transcripts (evidence: `app/ingest.py`)
- Ingestion workflow → Transcript chunking: chunks transcript (evidence: `app/ingest.py`)
- Transcript chunking → Text processing: normalizes text (evidence: `app/chunking.py`)
- Ingestion workflow → Corpus and chat DB: records corpus state (evidence: `app/ingest.py`)
- Ingestion workflow → Local hybrid search: indexes chunks (evidence: `app/ingest.py`)
- Video transcripts → YouTube: retrieves videos
- Daily updater → Ingestion workflow: runs updates (evidence: `app/scheduler.py`)
- Style dataset builder → Corpus and chat DB: reads corpus (evidence: `training/build_style_dataset.py`)
- Style dataset builder → Query and LLM: builds examples (evidence: `training/build_style_dataset.py`)
- Style dataset builder → LoRA training: provides reviewed data
- Answer synthesis → Gemini adapter: uses provider (evidence: `app/synthesis.py`)
- Answer synthesis → Search dispatch: uses search backend (evidence: `app/synthesis.py`)
