# xvoxlabs/bhagavad_gita architecture

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

- Interactive diagram: https://gitdiagram.com/xvoxlabs/bhagavad_gita
- Repository: https://github.com/xvoxlabs/bhagavad_gita

## Overview

Speak with Krishna is a Bhagavad Gita chat and chapter-reading application. The primary workflow runs from a user message in the chat experience through the chat API and response pipeline, which interprets intent, retrieves relevant verses, validates guidance, and returns a reply; session history supports follow-up turns. Separate capabilities provide chapter reading and daily verses, speech input/output, and a talking avatar. Edges are limited to relationships shown in excerpts, the source index, or the README; unsampled subsystem internals are not expanded.

Main entry points: [`src/lib/pipeline.ts`](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/pipeline.ts) (Response pipeline), [`src/lib/elevenlabs.ts`](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/elevenlabs.ts) (Speech provider client), [`src/app/api/chat/route.ts`](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/api/chat/route.ts) (Chat API), [`src/lib/corpus.ts`](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/corpus.ts) (Verse corpus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_chat_ui["Chat experience<br/>[chat-screen.tsx]"]
  node_sanctuary["Sanctuary interface"]
  node_chapter_reader["Chapter reader<br/>[page.tsx]"]
  node_daily_verse["Daily verse<br/>[daily.ts]"]
end

subgraph group_conversation["Conversation and guidance"]
  node_chat_api["Chat API<br/>[route.ts]"]
  node_pipeline["Response pipeline<br/>[pipeline.ts]"]
  node_llm["Language model<br/>[llm.ts]"]
  node_validation["Reply validation<br/>[verify.ts]"]
  node_safety["Safety checks<br/>[safety.ts]"]
  node_sessions[("Conversation sessions<br/>[session.ts]")]
end

subgraph group_scripture["Scripture and discovery"]
  node_corpus[("Verse corpus<br/>[corpus.ts]")]
  node_retrieval["Verse retrieval<br/>[retrieve.ts]"]
  node_themes["Theme matching<br/>[themes.ts]"]
  node_chapters["Chapter data<br/>[chapters.ts]"]
end

subgraph group_voice["Voice and avatar"]
  node_speech_ui["Speech controls<br/>[use-speech.ts]"]
  node_stt_api["Speech input API<br/>[route.ts]"]
  node_tts_api["Speech output API<br/>[route.ts]"]
  node_speech_provider["Speech provider client<br/>[elevenlabs.ts]"]
  node_avatar_engine["Avatar engine<br/>[anam-engine.ts]"]
  node_avatar_api["Avatar session API<br/>[route.ts]"]
  node_voice_api["Voice capabilities API<br/>[route.ts]"]
end

node_person(("Reader"))
node_elevenlabs{{"ElevenLabs"}}
node_anam{{"Anam avatar service"}}
node_model_service{{"LLM service"}}

node_person -->|"sends message"| node_chat_ui
node_chat_ui -->|"submits turn"| node_chat_api
node_chat_api -->|"requests response"| node_pipeline
node_chat_api -->|"loads and appends"| node_sessions
node_pipeline -->|"generates stages"| node_llm
node_pipeline -->|"selects verses"| node_retrieval
node_pipeline -->|"parses and checks"| node_validation
node_pipeline -->|"checks crisis"| node_safety
node_pipeline -->|"uses history"| node_sessions
node_llm -.->|"calls model"| node_model_service
node_retrieval -->|"ranks verses"| node_corpus
node_retrieval -->|"matches themes"| node_themes
node_validation -->|"checks citations"| node_corpus
node_person -->|"reads chapters"| node_chapter_reader
node_chapter_reader -->|"loads chapter"| node_chapters
node_chapters -->|"uses verse data"| node_corpus
node_person -->|"opens daily verse"| node_daily_verse
node_daily_verse -->|"loads verse"| node_corpus
node_person -->|"speaks or types"| node_sanctuary
node_sanctuary -.->|"sends chat"| node_chat_api
node_sanctuary -->|"controls avatar"| node_avatar_engine
node_speech_ui -.->|"transcribes audio"| node_stt_api
node_stt_api -->|"transcribes speech"| node_speech_provider
node_tts_api -->|"finds reply"| node_sessions
node_tts_api -->|"streams audio"| node_speech_provider
node_speech_provider -->|"requests speech"| node_elevenlabs
node_avatar_engine -->|"requests session"| node_avatar_api
node_avatar_api -.->|"creates session"| node_anam
node_avatar_api -->|"uses voice config"| node_speech_provider
node_voice_api -->|"checks availability"| node_speech_provider

click node_chat_ui "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/chat-screen.tsx"
click node_sanctuary "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/sanctuary-screen.tsx"
click node_chapter_reader "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/gita/%5Bchapter%5D/page.tsx"
click node_daily_verse "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/daily.ts"
click node_chat_api "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/api/chat/route.ts"
click node_pipeline "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/pipeline.ts"
click node_llm "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/llm.ts"
click node_validation "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/verify.ts"
click node_safety "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/safety.ts"
click node_sessions "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/session.ts"
click node_corpus "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/corpus.ts"
click node_retrieval "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/retrieve.ts"
click node_themes "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/themes.ts"
click node_chapters "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/chapters.ts"
click node_speech_ui "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/use-speech.ts"
click node_stt_api "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/api/stt/route.ts"
click node_tts_api "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/api/tts/route.ts"
click node_speech_provider "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/elevenlabs.ts"
click node_avatar_engine "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/avatar/anam-engine.ts"
click node_avatar_api "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/api/avatar/session/route.ts"
click node_voice_api "https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/api/voice/route.ts"

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_chat_ui,node_sanctuary,node_chapter_reader,node_daily_verse toneBlue
class node_chat_api,node_pipeline,node_llm,node_validation,node_safety,node_sessions toneAmber
class node_corpus,node_retrieval,node_themes,node_chapters toneMint
class node_speech_ui,node_stt_api,node_tts_api,node_speech_provider,node_avatar_engine,node_avatar_api,node_voice_api toneRose
class node_person,node_elevenlabs,node_anam,node_model_service toneIndigo
```

## Components

### User experience

- [Chat experience](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/chat-screen.tsx): `src/app/chat-screen.tsx`
- [Sanctuary interface](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/sanctuary-screen.tsx): `src/app/sanctuary-screen.tsx`
- [Chapter reader](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/gita/%5Bchapter%5D/page.tsx): `src/app/gita/[chapter]/page.tsx`
- [Daily verse](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/daily.ts): `src/lib/daily.ts`

### Conversation and guidance

- [Chat API](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Response pipeline](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/pipeline.ts): `src/lib/pipeline.ts`
- [Language model](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/llm.ts): `src/lib/llm.ts`
- [Reply validation](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/verify.ts): `src/lib/verify.ts`
- [Safety checks](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/safety.ts): `src/lib/safety.ts`
- [Conversation sessions](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/session.ts): `src/lib/session.ts`

### Scripture and discovery

- [Verse corpus](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/corpus.ts): `src/lib/corpus.ts`
- [Verse retrieval](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/retrieve.ts): `src/lib/retrieve.ts`
- [Theme matching](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/themes.ts): `src/lib/themes.ts`
- [Chapter data](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/chapters.ts): `src/lib/chapters.ts`

### Voice and avatar

- [Speech controls](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/use-speech.ts): `src/app/use-speech.ts`
- [Speech input API](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/api/stt/route.ts): `src/app/api/stt/route.ts`
- [Speech output API](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/api/tts/route.ts): `src/app/api/tts/route.ts`
- [Speech provider client](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/lib/elevenlabs.ts): `src/lib/elevenlabs.ts`
- [Avatar engine](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/avatar/anam-engine.ts): `src/app/avatar/anam-engine.ts`
- [Avatar session API](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/api/avatar/session/route.ts): `src/app/api/avatar/session/route.ts`
- [Voice capabilities API](https://github.com/xvoxlabs/bhagavad_gita/blob/main/src/app/api/voice/route.ts): `src/app/api/voice/route.ts`

### Other components

- **Reader**
- **ElevenLabs**
- **Anam avatar service**
- **LLM service**

## Connections

- Reader → Chat experience: sends message (evidence: `src/app/chat-screen.tsx`)
- Chat experience → Chat API: submits turn (evidence: `src/app/api/chat/route.ts`)
- Chat API → Response pipeline: requests response (evidence: `src/app/api/chat/route.ts`)
- Chat API → Conversation sessions: loads and appends (evidence: `src/app/api/chat/route.ts`)
- Response pipeline → Language model: generates stages (evidence: `src/lib/pipeline.ts`)
- Response pipeline → Verse retrieval: selects verses (evidence: `src/lib/pipeline.ts`)
- Response pipeline → Reply validation: parses and checks (evidence: `src/lib/pipeline.ts`)
- Response pipeline → Safety checks: checks crisis (evidence: `src/lib/pipeline.ts`)
- Response pipeline → Conversation sessions: uses history (evidence: `src/lib/pipeline.ts`)
- Language model → LLM service: calls model
- Verse retrieval → Verse corpus: ranks verses (evidence: `src/lib/retrieve.ts`)
- Verse retrieval → Theme matching: matches themes (evidence: `src/lib/retrieve.ts`)
- Reply validation → Verse corpus: checks citations (evidence: `src/lib/verify.ts`)
- Reader → Chapter reader: reads chapters (evidence: `src/app/gita/[chapter]/page.tsx`)
- Chapter reader → Chapter data: loads chapter (evidence: `src/app/gita/[chapter]/page.tsx`)
- Chapter data → Verse corpus: uses verse data (evidence: `src/lib/chapters.ts`)
- Reader → Daily verse: opens daily verse
- Daily verse → Verse corpus: loads verse (evidence: `src/lib/daily.ts`)
- Reader → Sanctuary interface: speaks or types (evidence: `src/app/sanctuary-screen.tsx`)
- Sanctuary interface → Chat API: sends chat
- Sanctuary interface → Avatar engine: controls avatar (evidence: `src/app/sanctuary-screen.tsx`)
- Speech controls → Speech input API: transcribes audio
- Speech input API → Speech provider client: transcribes speech (evidence: `src/app/api/stt/route.ts`)
- Speech output API → Conversation sessions: finds reply (evidence: `src/app/api/tts/route.ts`)
- Speech output API → Speech provider client: streams audio (evidence: `src/app/api/tts/route.ts`)
- Speech provider client → ElevenLabs: requests speech (evidence: `src/lib/elevenlabs.ts`)
- Avatar engine → Avatar session API: requests session (evidence: `src/app/avatar/anam-engine.ts`)
- Avatar session API → Anam avatar service: creates session
- Avatar session API → Speech provider client: uses voice config (evidence: `src/app/api/avatar/session/route.ts`)
- Voice capabilities API → Speech provider client: checks availability (evidence: `src/app/api/voice/route.ts`)
