# abhishekgiri1617/ai-receptionist architecture

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

- Interactive diagram: https://gitdiagram.com/abhishekgiri1617/ai-receptionist
- Repository: https://github.com/abhishekgiri1617/ai-receptionist

## Overview

This repository implements a configurable, voice-first customer-support receptionist. A caller speaks through a LiveKit session; speech is transcribed, the LangChain agent responds directly or routes the request to knowledge search, inquiry capture, or escalation, and the answer is spoken back. Separate ingestion prepares business documents for retrieval. The runtime also records transcripts and can synchronize conversation updates to an optional browser avatar UI. The README documents the main capabilities; some UI and integration internals were not sampled, so their connections are shown only where the excerpts support them.

Main entry points: [`voice_agent/main.py`](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/voice_agent/main.py) (Voice Entrypoint), [`langchain_agent/tools.py`](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/tools.py) (Agent Graph), [`langchain_agent/rag.py`](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/rag.py) (Retrieval and Context), [`voice_agent/transcript.py`](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/voice_agent/transcript.py) (Transcript Recorder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_voice["Voice Runtime"]
  node_speech["Speech I/O<br/>[main.py]"]
  node_voice_entry["Voice Entrypoint<br/>[main.py]"]
  node_settings["Runtime Settings<br/>[config.py]"]
  node_business_config["Business Persona<br/>[agent_config.yaml]"]
end

subgraph group_agent["Agent and Support"]
  node_agent_graph["Agent Graph<br/>[tools.py]"]
  node_knowledge_tool["Knowledge Search<br/>[tools.py]"]
  node_inquiry_capture["Inquiry Capture<br/>[tools.py]"]
  node_escalation["Human Escalation<br/>[tools.py]"]
  node_inquiry_log["Inquiry Log<br/>[tools.py]"]
  node_escalation_log["Escalation Log<br/>[tools.py]"]
end

subgraph group_knowledge["Knowledge Base"]
  node_ingestion["Document Ingestion<br/>[ingest.py]"]
  node_embedding_store["Embedding Store<br/>[db.py]"]
  node_qdrant[("Qdrant Index<br/>[db.py]")]
  node_rag["Retrieval and Context<br/>[rag.py]"]
end

subgraph group_records["Call Records"]
  node_transcript_recorder["Transcript Recorder<br/>[transcript.py]"]
  node_transcript_files["Transcript Files<br/>[transcript.py]"]
end

subgraph group_avatar["Avatar UI"]
  node_avatar_sync["Avatar Sync Server<br/>[sync_server.py]"]
  node_avatar_browser["Avatar Browser UI<br/>[app.js]"]
end

node_caller(("Caller"))
node_livekit["LiveKit Session"]
node_groq["Groq LLM"]

node_caller -->|"speaks to"| node_livekit
node_livekit -->|"starts session"| node_voice_entry
node_voice_entry -->|"configures"| node_speech
node_speech -->|"transcribes"| node_voice_entry
node_voice_entry -->|"adapts graph"| node_agent_graph
node_voice_entry -->|"records turns"| node_transcript_recorder
node_voice_entry -->|"notifies events"| node_avatar_sync
node_voice_entry -->|"reads persona"| node_business_config
node_voice_entry -->|"reads settings"| node_settings
node_agent_graph -->|"routes tools"| node_knowledge_tool
node_agent_graph -->|"routes tools"| node_inquiry_capture
node_agent_graph -->|"routes tools"| node_escalation
node_knowledge_tool -->|"retrieves context"| node_rag
node_rag -->|"embeds query"| node_embedding_store
node_rag -->|"searches vectors"| node_qdrant
node_rag -->|"generates answer"| node_groq
node_ingestion -->|"indexes chunks"| node_qdrant
node_ingestion -->|"generates embeddings"| node_embedding_store
node_inquiry_capture -->|"appends inquiry"| node_inquiry_log
node_escalation -->|"logs ticket"| node_escalation_log
node_transcript_recorder -->|"saves transcript"| node_transcript_files
node_transcript_recorder -->|"writes live turn"| node_avatar_sync
node_avatar_sync -->|"serves and broadcasts"| node_avatar_browser
node_agent_graph -.->|"returns response"| node_caller

click node_speech "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/voice_agent/main.py"
click node_voice_entry "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/voice_agent/main.py"
click node_settings "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/config.py"
click node_business_config "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/agent_config.yaml"
click node_agent_graph "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/tools.py"
click node_knowledge_tool "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/tools.py"
click node_inquiry_capture "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/tools.py"
click node_escalation "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/tools.py"
click node_inquiry_log "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/tools.py"
click node_escalation_log "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/tools.py"
click node_ingestion "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/ingest.py"
click node_embedding_store "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/db.py"
click node_qdrant "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/db.py"
click node_rag "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/rag.py"
click node_transcript_recorder "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/voice_agent/transcript.py"
click node_transcript_files "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/voice_agent/transcript.py"
click node_avatar_sync "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/avatar_agent_ui/sync_server.py"
click node_avatar_browser "https://github.com/abhishekgiri1617/ai-receptionist/blob/main/avatar_agent_ui/app.js"

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_speech,node_voice_entry,node_settings,node_business_config toneBlue
class node_agent_graph,node_knowledge_tool,node_inquiry_capture,node_escalation,node_inquiry_log,node_escalation_log toneAmber
class node_ingestion,node_embedding_store,node_qdrant,node_rag toneMint
class node_transcript_recorder,node_transcript_files toneRose
class node_avatar_sync,node_avatar_browser,node_caller,node_livekit,node_groq toneIndigo
```

## Components

### Voice Runtime

- [Speech I/O](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/voice_agent/main.py): `voice_agent/main.py`
- [Voice Entrypoint](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/voice_agent/main.py): `voice_agent/main.py`
- [Runtime Settings](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/config.py): `config.py`
- [Business Persona](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/agent_config.yaml): `agent_config.yaml`

### Agent and Support

- [Agent Graph](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/tools.py): `langchain_agent/tools.py`
- [Knowledge Search](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/tools.py): `langchain_agent/tools.py`
- [Inquiry Capture](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/tools.py): `langchain_agent/tools.py`
- [Human Escalation](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/tools.py): `langchain_agent/tools.py`
- [Inquiry Log](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/tools.py): `langchain_agent/tools.py`
- [Escalation Log](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/tools.py): `langchain_agent/tools.py`

### Knowledge Base

- [Document Ingestion](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/ingest.py): `ingest.py`
- [Embedding Store](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/db.py): `db.py`
- [Qdrant Index](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/db.py): `db.py`
- [Retrieval and Context](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/langchain_agent/rag.py): `langchain_agent/rag.py`

### Call Records

- [Transcript Recorder](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/voice_agent/transcript.py): `voice_agent/transcript.py`
- [Transcript Files](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/voice_agent/transcript.py): `voice_agent/transcript.py`

### Avatar UI

- [Avatar Sync Server](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/avatar_agent_ui/sync_server.py): `avatar_agent_ui/sync_server.py`
- [Avatar Browser UI](https://github.com/abhishekgiri1617/ai-receptionist/blob/main/avatar_agent_ui/app.js): `avatar_agent_ui/app.js`

### Other components

- **Caller**
- **LiveKit Session**
- **Groq LLM**

## Connections

- Caller → LiveKit Session: speaks to (evidence: `README.md`)
- LiveKit Session → Voice Entrypoint: starts session (evidence: `voice_agent/main.py`)
- Voice Entrypoint → Speech I/O: configures (evidence: `voice_agent/main.py`)
- Speech I/O → Voice Entrypoint: transcribes (evidence: `voice_agent/main.py`)
- Voice Entrypoint → Agent Graph: adapts graph (evidence: `voice_agent/main.py`)
- Voice Entrypoint → Transcript Recorder: records turns (evidence: `voice_agent/main.py`)
- Voice Entrypoint → Avatar Sync Server: notifies events (evidence: `voice_agent/main.py`)
- Voice Entrypoint → Business Persona: reads persona (evidence: `voice_agent/main.py`)
- Voice Entrypoint → Runtime Settings: reads settings (evidence: `voice_agent/main.py`)
- Agent Graph → Knowledge Search: routes tools (evidence: `langchain_agent/tools.py`)
- Agent Graph → Inquiry Capture: routes tools (evidence: `langchain_agent/tools.py`)
- Agent Graph → Human Escalation: routes tools (evidence: `langchain_agent/tools.py`)
- Knowledge Search → Retrieval and Context: retrieves context (evidence: `langchain_agent/tools.py`)
- Retrieval and Context → Embedding Store: embeds query (evidence: `langchain_agent/rag.py`)
- Retrieval and Context → Qdrant Index: searches vectors (evidence: `langchain_agent/rag.py`)
- Retrieval and Context → Groq LLM: generates answer (evidence: `langchain_agent/rag.py`)
- Document Ingestion → Qdrant Index: indexes chunks (evidence: `README.md`)
- Document Ingestion → Embedding Store: generates embeddings (evidence: `README.md`)
- Inquiry Capture → Inquiry Log: appends inquiry (evidence: `langchain_agent/tools.py`)
- Human Escalation → Escalation Log: logs ticket (evidence: `langchain_agent/tools.py`)
- Transcript Recorder → Transcript Files: saves transcript (evidence: `voice_agent/transcript.py`)
- Transcript Recorder → Avatar Sync Server: writes live turn (evidence: `voice_agent/transcript.py`)
- Avatar Sync Server → Avatar Browser UI: serves and broadcasts (evidence: `avatar_agent_ui/sync_server.py`)
- Agent Graph → Caller: returns response
