# im-shourya/voice-rag architecture

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

- Interactive diagram: https://gitdiagram.com/im-shourya/voice-rag
- Repository: https://github.com/im-shourya/voice-rag

## Overview

This is a bilingual voice-enabled RAG application over the MSMARCO-XI corpus. The main user path accepts audio or text, transcribes audio when needed, checks the query, retrieves and diversifies evidence, declines low-confidence requests, generates an extractive or optional LLM answer, then verifies it and returns citations and a trace. The repository also includes five-strategy chunking and hybrid-index support. The map follows documented pipeline relationships; some unsampled UI and optional-provider wiring is shown only where the README establishes it.

Main entry points: [`app/harness/orchestrator.py`](https://github.com/im-shourya/voice-rag/blob/main/app/harness/orchestrator.py) (RAG Orchestrator), [`app/retrieval/index_store.py`](https://github.com/im-shourya/voice-rag/blob/main/app/retrieval/index_store.py) (RAG Index), [`app/stt/registry.py`](https://github.com/im-shourya/voice-rag/blob/main/app/stt/registry.py) (STT Registry), [`app/chunking/pipeline.py`](https://github.com/im-shourya/voice-rag/blob/main/app/chunking/pipeline.py) (Chunking Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_web["Web Interface<br/>[page.tsx]"]
  node_recorder["Voice Recorder<br/>[useRecorder.ts]"]
end

subgraph group_runtime["Request Runtime"]
  node_http["HTTP API<br/>[main.py]"]
  node_pipeline["RAG Orchestrator<br/>[orchestrator.py]"]
  node_contracts["Request Contracts<br/>[schemas.py]"]
  node_stt["STT Registry<br/>[registry.py]"]
  node_sarvam["Sarvam STT<br/>[sarvam.py]"]
  node_elevenlabs["ElevenLabs STT<br/>[elevenlabs.py]"]
  node_trace["Stage Trace<br/>[trace.py]"]
end

subgraph group_retrieval["Evidence Retrieval"]
  node_embedder["Query Embedder<br/>[embedder.py]"]
  node_hybrid["Hybrid Retrieval<br/>[hybrid.py]"]
  node_index[("RAG Index<br/>[index_store.py]")]
  node_bm25[("BM25 Index<br/>[bm25.py]")]
  node_vectors[("Vector Store<br/>[vector_store.py]")]
end

subgraph group_answering["Answering and Safety"]
  node_inputguard["Input Guard<br/>[input_guard.py]"]
  node_intent["Intent Classifier<br/>[intent.py]"]
  node_extractive["Extractive Composer<br/>[extractive.py]"]
  node_llm["Optional LLM<br/>[llm.py]"]
  node_outputguard["Answer Verification<br/>[output_guard.py]"]
end

subgraph group_corpus["Corpus Preparation"]
  node_chunkpipe["Chunking Pipeline<br/>[pipeline.py]"]
  node_strategies["Chunk Strategies<br/>[strategies.py]"]
  node_corpusdata["MSMARCO-XI Corpus"]
end

node_user(("Questioner"))

node_user -->|"asks"| node_web
node_web -->|"submits text"| node_http
node_recorder -->|"submits audio"| node_http
node_http -->|"invokes"| node_pipeline
node_pipeline -->|"transcribes audio"| node_stt
node_stt -->|"dispatches"| node_sarvam
node_stt -->|"fails over"| node_elevenlabs
node_pipeline -->|"checks query"| node_inputguard
node_pipeline -->|"classifies"| node_intent
node_pipeline -->|"embeds query"| node_embedder
node_pipeline -->|"retrieves evidence"| node_hybrid
node_hybrid -->|"searches"| node_index
node_index -->|"uses sparse index"| node_bm25
node_index -->|"builds vector store"| node_vectors
node_pipeline -->|"composes answer"| node_extractive
node_pipeline -.->|"optionally generates"| node_llm
node_pipeline -->|"verifies draft"| node_outputguard
node_pipeline -->|"records spans"| node_trace
node_corpusdata -->|"provides passages"| node_chunkpipe
node_chunkpipe -->|"applies strategies"| node_strategies
node_chunkpipe -.->|"prepares chunks"| node_index

click node_web "https://github.com/im-shourya/voice-rag/blob/main/web/src/app/page.tsx"
click node_recorder "https://github.com/im-shourya/voice-rag/blob/main/web/src/lib/useRecorder.ts"
click node_http "https://github.com/im-shourya/voice-rag/blob/main/app/main.py"
click node_pipeline "https://github.com/im-shourya/voice-rag/blob/main/app/harness/orchestrator.py"
click node_contracts "https://github.com/im-shourya/voice-rag/blob/main/app/schemas.py"
click node_stt "https://github.com/im-shourya/voice-rag/blob/main/app/stt/registry.py"
click node_sarvam "https://github.com/im-shourya/voice-rag/blob/main/app/stt/sarvam.py"
click node_elevenlabs "https://github.com/im-shourya/voice-rag/blob/main/app/stt/elevenlabs.py"
click node_inputguard "https://github.com/im-shourya/voice-rag/blob/main/app/guardrails/input_guard.py"
click node_intent "https://github.com/im-shourya/voice-rag/blob/main/app/generation/intent.py"
click node_embedder "https://github.com/im-shourya/voice-rag/blob/main/app/retrieval/embedder.py"
click node_hybrid "https://github.com/im-shourya/voice-rag/blob/main/app/retrieval/hybrid.py"
click node_index "https://github.com/im-shourya/voice-rag/blob/main/app/retrieval/index_store.py"
click node_bm25 "https://github.com/im-shourya/voice-rag/blob/main/app/retrieval/bm25.py"
click node_vectors "https://github.com/im-shourya/voice-rag/blob/main/app/retrieval/vector_store.py"
click node_extractive "https://github.com/im-shourya/voice-rag/blob/main/app/generation/extractive.py"
click node_llm "https://github.com/im-shourya/voice-rag/blob/main/app/generation/llm.py"
click node_outputguard "https://github.com/im-shourya/voice-rag/blob/main/app/guardrails/output_guard.py"
click node_trace "https://github.com/im-shourya/voice-rag/blob/main/app/harness/trace.py"
click node_chunkpipe "https://github.com/im-shourya/voice-rag/blob/main/app/chunking/pipeline.py"
click node_strategies "https://github.com/im-shourya/voice-rag/blob/main/app/chunking/strategies.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_web,node_recorder toneBlue
class node_http,node_pipeline,node_contracts,node_stt,node_sarvam,node_elevenlabs,node_trace toneAmber
class node_embedder,node_hybrid,node_index,node_bm25,node_vectors toneMint
class node_inputguard,node_intent,node_extractive,node_llm,node_outputguard toneRose
class node_chunkpipe,node_strategies,node_corpusdata,node_user toneIndigo
```

## Components

### User Experience

- [Web Interface](https://github.com/im-shourya/voice-rag/blob/main/web/src/app/page.tsx): `web/src/app/page.tsx`
- [Voice Recorder](https://github.com/im-shourya/voice-rag/blob/main/web/src/lib/useRecorder.ts): `web/src/lib/useRecorder.ts`

### Request Runtime

- [HTTP API](https://github.com/im-shourya/voice-rag/blob/main/app/main.py): `app/main.py`
- [RAG Orchestrator](https://github.com/im-shourya/voice-rag/blob/main/app/harness/orchestrator.py): `app/harness/orchestrator.py`
- [Request Contracts](https://github.com/im-shourya/voice-rag/blob/main/app/schemas.py): `app/schemas.py`
- [STT Registry](https://github.com/im-shourya/voice-rag/blob/main/app/stt/registry.py): `app/stt/registry.py`
- [Sarvam STT](https://github.com/im-shourya/voice-rag/blob/main/app/stt/sarvam.py): `app/stt/sarvam.py`
- [ElevenLabs STT](https://github.com/im-shourya/voice-rag/blob/main/app/stt/elevenlabs.py): `app/stt/elevenlabs.py`
- [Stage Trace](https://github.com/im-shourya/voice-rag/blob/main/app/harness/trace.py): `app/harness/trace.py`

### Evidence Retrieval

- [Query Embedder](https://github.com/im-shourya/voice-rag/blob/main/app/retrieval/embedder.py): `app/retrieval/embedder.py`
- [Hybrid Retrieval](https://github.com/im-shourya/voice-rag/blob/main/app/retrieval/hybrid.py): `app/retrieval/hybrid.py`
- [RAG Index](https://github.com/im-shourya/voice-rag/blob/main/app/retrieval/index_store.py): `app/retrieval/index_store.py`
- [BM25 Index](https://github.com/im-shourya/voice-rag/blob/main/app/retrieval/bm25.py): `app/retrieval/bm25.py`
- [Vector Store](https://github.com/im-shourya/voice-rag/blob/main/app/retrieval/vector_store.py): `app/retrieval/vector_store.py`

### Answering and Safety

- [Input Guard](https://github.com/im-shourya/voice-rag/blob/main/app/guardrails/input_guard.py): `app/guardrails/input_guard.py`
- [Intent Classifier](https://github.com/im-shourya/voice-rag/blob/main/app/generation/intent.py): `app/generation/intent.py`
- [Extractive Composer](https://github.com/im-shourya/voice-rag/blob/main/app/generation/extractive.py): `app/generation/extractive.py`
- [Optional LLM](https://github.com/im-shourya/voice-rag/blob/main/app/generation/llm.py): `app/generation/llm.py`
- [Answer Verification](https://github.com/im-shourya/voice-rag/blob/main/app/guardrails/output_guard.py): `app/guardrails/output_guard.py`

### Corpus Preparation

- [Chunking Pipeline](https://github.com/im-shourya/voice-rag/blob/main/app/chunking/pipeline.py): `app/chunking/pipeline.py`
- [Chunk Strategies](https://github.com/im-shourya/voice-rag/blob/main/app/chunking/strategies.py): `app/chunking/strategies.py`
- **MSMARCO-XI Corpus**

### Other components

- **Questioner**

## Connections

- Questioner → Web Interface: asks
- Web Interface → HTTP API: submits text
- Voice Recorder → HTTP API: submits audio
- HTTP API → RAG Orchestrator: invokes (evidence: `app/main.py`)
- RAG Orchestrator → STT Registry: transcribes audio (evidence: `app/harness/orchestrator.py`)
- STT Registry → Sarvam STT: dispatches (evidence: `app/stt/registry.py`)
- STT Registry → ElevenLabs STT: fails over (evidence: `app/stt/registry.py`)
- RAG Orchestrator → Input Guard: checks query (evidence: `app/harness/orchestrator.py`)
- RAG Orchestrator → Intent Classifier: classifies (evidence: `app/harness/orchestrator.py`)
- RAG Orchestrator → Query Embedder: embeds query (evidence: `app/harness/orchestrator.py`)
- RAG Orchestrator → Hybrid Retrieval: retrieves evidence (evidence: `app/harness/orchestrator.py`)
- Hybrid Retrieval → RAG Index: searches (evidence: `app/retrieval/hybrid.py`)
- RAG Index → BM25 Index: uses sparse index (evidence: `app/retrieval/index_store.py`)
- RAG Index → Vector Store: builds vector store (evidence: `app/retrieval/index_store.py`)
- RAG Orchestrator → Extractive Composer: composes answer (evidence: `app/harness/orchestrator.py`)
- RAG Orchestrator → Optional LLM: optionally generates (evidence: `app/harness/orchestrator.py`)
- RAG Orchestrator → Answer Verification: verifies draft (evidence: `app/harness/orchestrator.py`)
- RAG Orchestrator → Stage Trace: records spans (evidence: `app/harness/orchestrator.py`)
- MSMARCO-XI Corpus → Chunking Pipeline: provides passages
- Chunking Pipeline → Chunk Strategies: applies strategies (evidence: `app/chunking/pipeline.py`)
- Chunking Pipeline → RAG Index: prepares chunks
