# austecch/helix-ai-virtual-receptionist architecture

> Architecture diagram of the GitHub repository austecch/helix-ai-virtual-receptionist, 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/austecch/helix-ai-virtual-receptionist
- Repository: https://github.com/austecch/helix-ai-virtual-receptionist

## Overview

Helix is a self-hosted AI receptionist: Asterisk call events enter the Python agent, which handles caller audio, intent and policy, then responds, schedules, or routes to a person. The FastAPI API and web dashboard expose operational data and controls. The README documents major capabilities not visible in the sampled code, including after-hours handling, translation relay, voicemail, and CRM synchronization; these are represented at the agent boundary where their implementation details were not sampled. Dashboard-to-agent API wiring is documented, but individual page requests are not evidenced here.

Main entry points: [`agent/ari_agent.py`](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/ari_agent.py) (Call orchestrator), [`dashboard/client/src/App.tsx`](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/dashboard/client/src/App.tsx) (Web dashboard), [`agent/database.py`](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/database.py) (Call and operations data), [`agent/api.py`](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/api.py) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_calls["Call handling"]
  node_agent["Call orchestrator<br/>[ari_agent.py]"]
  node_api["REST API<br/>[api.py]"]
end

subgraph group_ai["Voice intelligence"]
  node_audio["Voice activity detection<br/>[silero_engine.py]"]
  node_transcription["Speech recognition<br/>[whisper_engine.py]"]
  node_intent["Intent conversation<br/>[intent_engine.py]"]
  node_translation["Translation engine"]
  node_speech["Speech synthesis<br/>[kokoro_engine.py]"]
end

subgraph group_operations["Operations and integrations"]
  node_routing["Extension routing<br/>[router.py]"]
  node_agents["Agent availability<br/>[agents.py]"]
  node_database[("Call and operations data<br/>[database.py]")]
  node_calendar["Calendar scheduling<br/>[gcal.py]"]
  node_crm["Vtiger CRM<br/>[vtiger.py]"]
end

subgraph group_dashboard["Operations dashboard"]
  node_dashboard["Web dashboard<br/>[App.tsx]"]
  node_pages["Operations pages"]
  node_server["Dashboard API server<br/>[routes.ts]"]
  node_storage[("Dashboard storage<br/>[storage.ts]")]
end

node_caller(("Caller"))
node_asterisk["Asterisk PBX"]
node_operator(("Business operator"))
node_google["Google Calendar"]
node_vtiger_service["Vtiger service"]

node_caller -->|"calls"| node_asterisk
node_asterisk -->|"sends call events"| node_agent
node_agent -->|"detects speech"| node_audio
node_agent -->|"transcribes audio"| node_transcription
node_agent -->|"detects intent"| node_intent
node_agent -->|"translates speech"| node_translation
node_agent -->|"synthesizes replies"| node_speech
node_agent -->|"looks up routes"| node_routing
node_agent -->|"claims agents"| node_agents
node_agent -->|"books appointments"| node_calendar
node_agent -->|"syncs caller records"| node_crm
node_agent -->|"records call data"| node_database
node_routing -->|"reads routing rules"| node_database
node_agents -->|"reads agent state"| node_database
node_calendar -->|"queries and books"| node_google
node_crm -.->|"uses CRM API"| node_vtiger_service
node_agent -->|"controls call legs"| node_asterisk
node_api -->|"serves operations data"| node_database
node_dashboard -.->|"presents operations"| node_pages
node_operator -->|"manages operations"| node_dashboard
node_dashboard -.->|"requests dashboard API"| node_server
node_server -->|"reads and writes"| node_storage
node_dashboard -->|"uses REST API"| node_api
node_agent -->|"runs alongside"| node_api

click node_agent "https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/ari_agent.py"
click node_api "https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/api.py"
click node_audio "https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/vad/silero_engine.py"
click node_transcription "https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/stt/whisper_engine.py"
click node_intent "https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/llm/intent_engine.py"
click node_translation "https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/llm/translate_engine.py"
click node_speech "https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/tts/kokoro_engine.py"
click node_routing "https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/routing/router.py"
click node_agents "https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/routing/agents.py"
click node_database "https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/database.py"
click node_calendar "https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/gcal/gcal.py"
click node_crm "https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/integrations/vtiger.py"
click node_dashboard "https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/dashboard/client/src/App.tsx"
click node_pages "https://github.com/austecch/helix-ai-virtual-receptionist/tree/main/dashboard/client/src/pages"
click node_server "https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/dashboard/server/routes.ts"
click node_storage "https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/dashboard/server/storage.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_agent,node_api toneBlue
class node_audio,node_transcription,node_intent,node_translation,node_speech toneAmber
class node_routing,node_agents,node_database,node_calendar,node_crm toneMint
class node_dashboard,node_pages,node_server,node_storage toneRose
class node_caller,node_asterisk,node_operator,node_google,node_vtiger_service toneIndigo
```

## Components

### Call handling

- [Call orchestrator](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/ari_agent.py): `agent/ari_agent.py`
- [REST API](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/api.py): `agent/api.py`

### Voice intelligence

- [Voice activity detection](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/vad/silero_engine.py): `agent/vad/silero_engine.py`
- [Speech recognition](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/stt/whisper_engine.py): `agent/stt/whisper_engine.py`
- [Intent conversation](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/llm/intent_engine.py): `agent/llm/intent_engine.py`
- [Translation engine](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/llm/translate_engine.py): `agent/llm/translate_engine.py`
- [Speech synthesis](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/tts/kokoro_engine.py): `agent/tts/kokoro_engine.py`

### Operations and integrations

- [Extension routing](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/routing/router.py): `agent/routing/router.py`
- [Agent availability](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/routing/agents.py): `agent/routing/agents.py`
- [Call and operations data](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/database.py): `agent/database.py`
- [Calendar scheduling](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/gcal/gcal.py): `agent/gcal/gcal.py`
- [Vtiger CRM](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/agent/integrations/vtiger.py): `agent/integrations/vtiger.py`

### Operations dashboard

- [Web dashboard](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/dashboard/client/src/App.tsx): `dashboard/client/src/App.tsx`
- [Operations pages](https://github.com/austecch/helix-ai-virtual-receptionist/tree/main/dashboard/client/src/pages): `dashboard/client/src/pages`
- [Dashboard API server](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/dashboard/server/routes.ts): `dashboard/server/routes.ts`
- [Dashboard storage](https://github.com/austecch/helix-ai-virtual-receptionist/blob/main/dashboard/server/storage.ts): `dashboard/server/storage.ts`

### Other components

- **Caller**
- **Asterisk PBX**
- **Business operator**
- **Google Calendar**
- **Vtiger service**

## Connections

- Caller → Asterisk PBX: calls (evidence: `README.md`)
- Asterisk PBX → Call orchestrator: sends call events (evidence: `README.md`)
- Call orchestrator → Voice activity detection: detects speech (evidence: `agent/ari_agent.py`)
- Call orchestrator → Speech recognition: transcribes audio (evidence: `agent/ari_agent.py`)
- Call orchestrator → Intent conversation: detects intent (evidence: `agent/ari_agent.py`)
- Call orchestrator → Translation engine: translates speech (evidence: `agent/ari_agent.py`)
- Call orchestrator → Speech synthesis: synthesizes replies (evidence: `agent/ari_agent.py`)
- Call orchestrator → Extension routing: looks up routes (evidence: `agent/ari_agent.py`)
- Call orchestrator → Agent availability: claims agents (evidence: `agent/ari_agent.py`)
- Call orchestrator → Calendar scheduling: books appointments (evidence: `agent/ari_agent.py`)
- Call orchestrator → Vtiger CRM: syncs caller records (evidence: `agent/ari_agent.py`)
- Call orchestrator → Call and operations data: records call data (evidence: `agent/ari_agent.py`)
- Extension routing → Call and operations data: reads routing rules (evidence: `agent/routing/router.py`)
- Agent availability → Call and operations data: reads agent state (evidence: `agent/routing/agents.py`)
- Calendar scheduling → Google Calendar: queries and books (evidence: `README.md`)
- Vtiger CRM → Vtiger service: uses CRM API (evidence: `README.md`)
- Call orchestrator → Asterisk PBX: controls call legs (evidence: `README.md`)
- REST API → Call and operations data: serves operations data (evidence: `agent/api.py`)
- Web dashboard → Operations pages: presents operations
- Business operator → Web dashboard: manages operations (evidence: `README.md`)
- Web dashboard → Dashboard API server: requests dashboard API
- Dashboard API server → Dashboard storage: reads and writes (evidence: `dashboard/server/routes.ts`)
- Web dashboard → REST API: uses REST API (evidence: `README.md`)
- Call orchestrator → REST API: runs alongside (evidence: `agent/main.py`)
