# kolomfolox-lab/ai_receptionist architecture

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

- Interactive diagram: https://gitdiagram.com/kolomfolox-lab/ai_receptionist
- Repository: https://github.com/kolomfolox-lab/ai_receptionist

## Overview

VoiceAI Studio is a multi-agent AI receptionist with browser and Twilio voice entry points plus an authenticated management dashboard. The primary call path receives audio, segments speech, transcribes it, generates a receptionist reply, synthesizes audio, and returns it to the caller; call records feed dashboard statistics. The tree also exposes booking, intake, messaging, recording, transcript, and retention subsystems. The server and voice pipeline excerpts support the main call-flow links; wiring for several additional subsystems is not shown, so those links are omitted.

Main entry points: [`receptionist/voice/pipeline.py`](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/voice/pipeline.py) (Voice pipeline), [`server.py`](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/server.py) (API and sessions), [`frontend/src/store/useStore.js`](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/frontend/src/store/useStore.js) (API and UI state), [`receptionist/database.py`](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/database.py) (Agents and calls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_call_runtime["Voice runtime"]
  node_server["API and sessions<br/>[server.py]"]
  node_pipeline["Voice pipeline<br/>[pipeline.py]"]
  node_vad["Speech detection<br/>[vad.py]"]
  node_stt["Speech recognition<br/>[stt.py]"]
  node_agent["Receptionist agent<br/>[agent.py]"]
  node_tts["Speech synthesis<br/>[tts.py]"]
end

subgraph group_management["Management app"]
  node_browser_app["Reception dashboard<br/>[App.jsx]"]
  node_frontend_store["API and UI state<br/>[useStore.js]"]
  node_agents_page["Agent management<br/>[AgentsPage.jsx]"]
  node_playground_page["Conversation playground<br/>[PlaygroundPage.jsx]"]
  node_analytics_page["Analytics<br/>[AnalyticsPage.jsx]"]
  node_activity_page["Call activity<br/>[ActivityPage.jsx]"]
  node_settings_page["Settings<br/>[SettingsPage.jsx]"]
end

subgraph group_business_ops["Business operations"]
  node_database[("Agents and calls<br/>[database.py]")]
  node_booking["Booking workflow<br/>[booking.py]"]
  node_availability["Availability lookup<br/>[availability.py]"]
  node_calendar_client["Calendar client<br/>[client.py]"]
  node_intake_storage[("Intake submissions<br/>[storage.py]")]
end

subgraph group_support_services["Call support"]
  node_message_dispatcher["Message dispatch<br/>[dispatcher.py]"]
  node_webhook_channel["Webhook channel<br/>[webhook.py]"]
  node_recording["Call recordings<br/>[storage.py]"]
  node_transcript["Transcript capture<br/>[capture.py]"]
  node_retention["Retention sweeper<br/>[sweeper.py]"]
end

node_browser_caller(("Browser caller"))
node_phone_caller(("Phone caller"))
node_llm_service["LLM service"]
node_google_calendar["Google Calendar"]
node_webhook_service["Webhook receiver"]

node_browser_caller -->|"sends audio"| node_server
node_phone_caller -->|"calls"| node_server
node_server -->|"creates session"| node_pipeline
node_server -->|"feeds audio"| node_pipeline
node_pipeline -->|"segments speech"| node_vad
node_pipeline -->|"transcribes audio"| node_stt
node_pipeline -->|"handles turn"| node_agent
node_agent -.->|"generates reply"| node_llm_service
node_pipeline -->|"synthesizes reply"| node_tts
node_pipeline -->|"returns audio"| node_server
node_server -->|"streams audio"| node_browser_caller
node_server -->|"streams audio"| node_phone_caller
node_browser_app -->|"reads state"| node_frontend_store
node_frontend_store -->|"calls API"| node_server
node_agents_page -->|"uses API"| node_frontend_store
node_playground_page -->|"uses API"| node_frontend_store
node_analytics_page -->|"uses API"| node_frontend_store
node_activity_page -->|"uses API"| node_frontend_store
node_settings_page -->|"uses API"| node_frontend_store
node_server -->|"reads and writes"| node_database
node_pipeline -->|"loads agent"| node_database
node_pipeline -->|"logs call"| node_database
node_calendar_client -->|"queries and updates"| node_google_calendar
node_availability -->|"checks calendar"| node_calendar_client
node_booking -->|"checks availability"| node_availability
node_message_dispatcher -->|"dispatches message"| node_webhook_channel
node_webhook_channel -->|"posts message"| node_webhook_service

click node_server "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/server.py"
click node_pipeline "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/voice/pipeline.py"
click node_vad "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/voice/vad.py"
click node_stt "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/voice/stt.py"
click node_agent "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/agent.py"
click node_tts "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/voice/tts.py"
click node_browser_app "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/frontend/src/App.jsx"
click node_frontend_store "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/frontend/src/store/useStore.js"
click node_agents_page "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/frontend/src/pages/AgentsPage.jsx"
click node_playground_page "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/frontend/src/pages/PlaygroundPage.jsx"
click node_analytics_page "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/frontend/src/pages/AnalyticsPage.jsx"
click node_activity_page "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/frontend/src/pages/ActivityPage.jsx"
click node_settings_page "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/frontend/src/pages/SettingsPage.jsx"
click node_database "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/database.py"
click node_booking "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/booking/booking.py"
click node_availability "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/booking/availability.py"
click node_calendar_client "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/booking/client.py"
click node_intake_storage "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/intakes/storage.py"
click node_message_dispatcher "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/messaging/dispatcher.py"
click node_webhook_channel "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/messaging/channels/webhook.py"
click node_recording "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/recording/storage.py"
click node_transcript "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/transcript/capture.py"
click node_retention "https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/retention/sweeper.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_server,node_pipeline,node_vad,node_stt,node_agent,node_tts,node_browser_caller toneBlue
class node_browser_app,node_frontend_store,node_agents_page,node_playground_page,node_analytics_page,node_activity_page,node_settings_page toneAmber
class node_database,node_booking,node_availability,node_calendar_client,node_intake_storage,node_webhook_service toneMint
class node_message_dispatcher,node_webhook_channel,node_recording,node_transcript,node_retention toneRose
class node_phone_caller,node_llm_service,node_google_calendar toneIndigo
```

## Components

### Voice runtime

- [API and sessions](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/server.py): `server.py`
- [Voice pipeline](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/voice/pipeline.py): `receptionist/voice/pipeline.py`
- [Speech detection](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/voice/vad.py): `receptionist/voice/vad.py`
- [Speech recognition](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/voice/stt.py): `receptionist/voice/stt.py`
- [Receptionist agent](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/agent.py): `receptionist/agent.py`
- [Speech synthesis](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/voice/tts.py): `receptionist/voice/tts.py`

### Management app

- [Reception dashboard](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API and UI state](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/frontend/src/store/useStore.js): `frontend/src/store/useStore.js`
- [Agent management](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/frontend/src/pages/AgentsPage.jsx): `frontend/src/pages/AgentsPage.jsx`
- [Conversation playground](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/frontend/src/pages/PlaygroundPage.jsx): `frontend/src/pages/PlaygroundPage.jsx`
- [Analytics](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/frontend/src/pages/AnalyticsPage.jsx): `frontend/src/pages/AnalyticsPage.jsx`
- [Call activity](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/frontend/src/pages/ActivityPage.jsx): `frontend/src/pages/ActivityPage.jsx`
- [Settings](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/frontend/src/pages/SettingsPage.jsx): `frontend/src/pages/SettingsPage.jsx`

### Business operations

- [Agents and calls](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/database.py): `receptionist/database.py`
- [Booking workflow](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/booking/booking.py): `receptionist/booking/booking.py`
- [Availability lookup](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/booking/availability.py): `receptionist/booking/availability.py`
- [Calendar client](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/booking/client.py): `receptionist/booking/client.py`
- [Intake submissions](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/intakes/storage.py): `receptionist/intakes/storage.py`

### Call support

- [Message dispatch](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/messaging/dispatcher.py): `receptionist/messaging/dispatcher.py`
- [Webhook channel](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/messaging/channels/webhook.py): `receptionist/messaging/channels/webhook.py`
- [Call recordings](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/recording/storage.py): `receptionist/recording/storage.py`
- [Transcript capture](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/transcript/capture.py): `receptionist/transcript/capture.py`
- [Retention sweeper](https://github.com/kolomfolox-lab/ai_receptionist/blob/main/receptionist/retention/sweeper.py): `receptionist/retention/sweeper.py`

### Other components

- **Browser caller**
- **Phone caller**
- **LLM service**
- **Google Calendar**
- **Webhook receiver**

## Connections

- Browser caller → API and sessions: sends audio
- Phone caller → API and sessions: calls
- API and sessions → Voice pipeline: creates session
- API and sessions → Voice pipeline: feeds audio
- Voice pipeline → Speech detection: segments speech
- Voice pipeline → Speech recognition: transcribes audio
- Voice pipeline → Receptionist agent: handles turn
- Receptionist agent → LLM service: generates reply
- Voice pipeline → Speech synthesis: synthesizes reply
- Voice pipeline → API and sessions: returns audio
- API and sessions → Browser caller: streams audio
- API and sessions → Phone caller: streams audio
- Reception dashboard → API and UI state: reads state
- API and UI state → API and sessions: calls API
- Agent management → API and UI state: uses API
- Conversation playground → API and UI state: uses API
- Analytics → API and UI state: uses API
- Call activity → API and UI state: uses API
- Settings → API and UI state: uses API
- API and sessions → Agents and calls: reads and writes
- Voice pipeline → Agents and calls: loads agent
- Voice pipeline → Agents and calls: logs call
- Calendar client → Google Calendar: queries and updates
- Availability lookup → Calendar client: checks calendar
- Booking workflow → Availability lookup: checks availability
- Message dispatch → Webhook channel: dispatches message
- Webhook channel → Webhook receiver: posts message