# kamalesh-suresh-kumar/rec-voice-ai-receptionist architecture

> Architecture diagram of the GitHub repository kamalesh-suresh-kumar/rec-voice-ai-receptionist, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist
- Repository: https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist

## Overview

REC Voice AI Receptionist answers callers’ public institutional-information questions through a SIP/Asterisk call, AudioSocket audio gateway, speech recognition, RAG-grounded response generation, and speech playback. A separate ingestion workflow prepares website and PDF material for semantic retrieval. The README also documents evaluation capabilities and a planned Phase 2 for authenticated student queries and receptionist escalation; Phase 2 is not represented as implemented runtime behavior. Relationships below follow shown calls or README architecture statements; some optional and unsampled integrations are omitted.

Main entry points: [`REC-Voice-AI-Receptionist/backend/app/rag/rag_service.py`](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/rag/rag_service.py) (RAG orchestrator), [`REC-Voice-AI-Receptionist/backend/app/telephony/audio_gateway.py`](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/telephony/audio_gateway.py) (Audio gateway), [`REC-Voice-AI-Receptionist/backend/app/ingestion/pipeline.py`](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/ingestion/pipeline.py) (Ingestion pipeline), [`REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_voice_latency.py`](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_voice_latency.py) (Voice latency evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telephony["Call handling"]
  node_asterisk["Asterisk"]
  node_gateway["Audio gateway<br/>[audio_gateway.py]"]
end

subgraph group_voice["Voice processing"]
  node_vad["Speech detection<br/>[audio_gateway.py]"]
  node_stt["Speech recognition<br/>[stt_service.py]"]
  node_cuda["CUDA setup<br/>[cuda_setup.py]"]
  node_tts["Speech synthesis<br/>[tts_service.py]"]
end

subgraph group_knowledge["Knowledge preparation"]
  node_webscraper["Web extraction<br/>[web_scraper.py]"]
  node_pdfparser["PDF and OCR extraction<br/>[pdf_parser.py]"]
  node_ingestion["Ingestion pipeline<br/>[pipeline.py]"]
  node_chunker["Text chunking<br/>[chunker.py]"]
end

subgraph group_answering["Grounded answering"]
  node_rag["RAG orchestrator<br/>[rag_service.py]"]
  node_retriever["Semantic retrieval<br/>[retriever.py]"]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
  node_vector[("Chroma knowledge store<br/>[vector_store.py]")]
  node_llm["Grounded response<br/>[llm_service.py]"]
end

subgraph group_evaluation["Quality evaluation"]
  node_evalrag["RAG evaluation<br/>[evaluate_rag.py]"]
  node_evalares["ARES evaluation<br/>[evaluate_ares.py]"]
  node_evalragas["RAGAS evaluation<br/>[evaluate_ragas.py]"]
  node_latency["Voice latency evaluation"]
end

node_caller(("SIP caller"))
node_ollama["Ollama / Gemma"]
node_website["College website content"]
node_pdfs["Institutional PDFs"]

node_caller -->|"calls via SIP"| node_asterisk
node_asterisk -->|"opens AudioSocket"| node_gateway
node_gateway -->|"detects speech"| node_vad
node_gateway -->|"transcribes audio"| node_stt
node_stt -->|"configures"| node_cuda
node_gateway -->|"asks query"| node_rag
node_rag -->|"searches"| node_retriever
node_retriever -->|"embeds query"| node_embeddings
node_retriever -->|"queries"| node_vector
node_rag -->|"generates answer"| node_llm
node_llm -->|"requests generation"| node_ollama
node_gateway -->|"synthesizes reply"| node_tts
node_gateway -->|"sends audio"| node_asterisk
node_asterisk -->|"plays response"| node_caller
node_website -.->|"provides content"| node_webscraper
node_pdfs -->|"provides documents"| node_pdfparser
node_ingestion -->|"extracts PDFs"| node_pdfparser
node_ingestion -->|"chunks text"| node_chunker
node_ingestion -->|"encodes chunks"| node_embeddings
node_ingestion -->|"stores chunks"| node_vector
node_webscraper -.->|"supplies web content"| node_ingestion
node_evalrag -->|"evaluates answers"| node_rag
node_evalares -->|"evaluates quality"| node_rag
node_evalragas -->|"evaluates quality"| node_rag
node_latency -->|"measures latency"| node_rag
node_latency -->|"measures latency"| node_stt
node_latency -->|"measures latency"| node_tts

click node_gateway "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/telephony/audio_gateway.py"
click node_vad "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/telephony/audio_gateway.py"
click node_stt "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/voice/stt_service.py"
click node_cuda "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/voice/cuda_setup.py"
click node_rag "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/rag/rag_service.py"
click node_retriever "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/rag/retriever.py"
click node_embeddings "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/rag/embeddings.py"
click node_vector "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/rag/vector_store.py"
click node_llm "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/rag/llm_service.py"
click node_tts "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/voice/tts_service.py"
click node_webscraper "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/ingestion/web_scraper.py"
click node_pdfparser "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/ingestion/pdf_parser.py"
click node_ingestion "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/ingestion/pipeline.py"
click node_chunker "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/ingestion/chunker.py"
click node_evalrag "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_rag.py"
click node_evalares "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_ares.py"
click node_evalragas "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_ragas.py"
click node_latency "https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_voice_latency.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_asterisk,node_gateway toneBlue
class node_vad,node_stt,node_cuda,node_tts toneAmber
class node_webscraper,node_pdfparser,node_ingestion,node_chunker toneMint
class node_rag,node_retriever,node_embeddings,node_vector,node_llm toneRose
class node_evalrag,node_evalares,node_evalragas,node_latency,node_caller,node_ollama,node_website,node_pdfs toneIndigo
```

## Components

### Call handling

- **Asterisk**
- [Audio gateway](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/telephony/audio_gateway.py): `REC-Voice-AI-Receptionist/backend/app/telephony/audio_gateway.py`

### Voice processing

- [Speech detection](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/telephony/audio_gateway.py): `REC-Voice-AI-Receptionist/backend/app/telephony/audio_gateway.py`
- [Speech recognition](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/voice/stt_service.py): `REC-Voice-AI-Receptionist/backend/app/voice/stt_service.py`
- [CUDA setup](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/voice/cuda_setup.py): `REC-Voice-AI-Receptionist/backend/app/voice/cuda_setup.py`
- [Speech synthesis](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/voice/tts_service.py): `REC-Voice-AI-Receptionist/backend/app/voice/tts_service.py`

### Knowledge preparation

- [Web extraction](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/ingestion/web_scraper.py): `REC-Voice-AI-Receptionist/backend/app/ingestion/web_scraper.py`
- [PDF and OCR extraction](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/ingestion/pdf_parser.py): `REC-Voice-AI-Receptionist/backend/app/ingestion/pdf_parser.py`
- [Ingestion pipeline](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/ingestion/pipeline.py): `REC-Voice-AI-Receptionist/backend/app/ingestion/pipeline.py`
- [Text chunking](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/ingestion/chunker.py): `REC-Voice-AI-Receptionist/backend/app/ingestion/chunker.py`

### Grounded answering

- [RAG orchestrator](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/rag/rag_service.py): `REC-Voice-AI-Receptionist/backend/app/rag/rag_service.py`
- [Semantic retrieval](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/rag/retriever.py): `REC-Voice-AI-Receptionist/backend/app/rag/retriever.py`
- [Embeddings](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/rag/embeddings.py): `REC-Voice-AI-Receptionist/backend/app/rag/embeddings.py`
- [Chroma knowledge store](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/rag/vector_store.py): `REC-Voice-AI-Receptionist/backend/app/rag/vector_store.py`
- [Grounded response](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/rag/llm_service.py): `REC-Voice-AI-Receptionist/backend/app/rag/llm_service.py`

### Quality evaluation

- [RAG evaluation](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_rag.py): `REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_rag.py`
- [ARES evaluation](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_ares.py): `REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_ares.py`
- [RAGAS evaluation](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_ragas.py): `REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_ragas.py`
- [Voice latency evaluation](https://github.com/kamalesh-suresh-kumar/rec-voice-ai-receptionist/blob/main/REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_voice_latency.py): `REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_voice_latency.py`

### Other components

- **SIP caller**
- **Ollama / Gemma**
- **College website content**
- **Institutional PDFs**

## Connections

- SIP caller → Asterisk: calls via SIP (evidence: `README.md`)
- Asterisk → Audio gateway: opens AudioSocket (evidence: `README.md`)
- Audio gateway → Speech detection: detects speech (evidence: `README.md`)
- Audio gateway → Speech recognition: transcribes audio (evidence: `REC-Voice-AI-Receptionist/backend/app/telephony/audio_gateway.py`)
- Speech recognition → CUDA setup: configures (evidence: `REC-Voice-AI-Receptionist/backend/app/voice/stt_service.py`)
- Audio gateway → RAG orchestrator: asks query (evidence: `REC-Voice-AI-Receptionist/backend/app/telephony/audio_gateway.py`)
- RAG orchestrator → Semantic retrieval: searches (evidence: `REC-Voice-AI-Receptionist/backend/app/rag/rag_service.py`)
- Semantic retrieval → Embeddings: embeds query (evidence: `REC-Voice-AI-Receptionist/backend/app/rag/retriever.py`)
- Semantic retrieval → Chroma knowledge store: queries (evidence: `REC-Voice-AI-Receptionist/backend/app/rag/retriever.py`)
- RAG orchestrator → Grounded response: generates answer (evidence: `REC-Voice-AI-Receptionist/backend/app/rag/rag_service.py`)
- Grounded response → Ollama / Gemma: requests generation (evidence: `REC-Voice-AI-Receptionist/backend/app/rag/llm_service.py`)
- Audio gateway → Speech synthesis: synthesizes reply (evidence: `REC-Voice-AI-Receptionist/backend/app/telephony/audio_gateway.py`)
- Audio gateway → Asterisk: sends audio (evidence: `README.md`)
- Asterisk → SIP caller: plays response (evidence: `README.md`)
- College website content → Web extraction: provides content (evidence: `README.md`)
- Institutional PDFs → PDF and OCR extraction: provides documents (evidence: `README.md`)
- Ingestion pipeline → PDF and OCR extraction: extracts PDFs (evidence: `REC-Voice-AI-Receptionist/backend/app/ingestion/pipeline.py`)
- Ingestion pipeline → Text chunking: chunks text (evidence: `REC-Voice-AI-Receptionist/backend/app/ingestion/pipeline.py`)
- Ingestion pipeline → Embeddings: encodes chunks (evidence: `REC-Voice-AI-Receptionist/backend/app/ingestion/pipeline.py`)
- Ingestion pipeline → Chroma knowledge store: stores chunks (evidence: `REC-Voice-AI-Receptionist/backend/app/ingestion/pipeline.py`)
- Web extraction → Ingestion pipeline: supplies web content (evidence: `README.md`)
- RAG evaluation → RAG orchestrator: evaluates answers (evidence: `REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_rag.py`)
- ARES evaluation → RAG orchestrator: evaluates quality (evidence: `REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_ares.py`)
- RAGAS evaluation → RAG orchestrator: evaluates quality (evidence: `REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_ragas.py`)
- Voice latency evaluation → RAG orchestrator: measures latency (evidence: `REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_voice_latency.py`)
- Voice latency evaluation → Speech recognition: measures latency (evidence: `REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_voice_latency.py`)
- Voice latency evaluation → Speech synthesis: measures latency (evidence: `REC-Voice-AI-Receptionist/backend/app/evaluation/evaluate_voice_latency.py`)
