# kirklandsig/aireceptionist architecture

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

- Interactive diagram: https://gitdiagram.com/kirklandsig/aireceptionist
- Repository: https://github.com/kirklandsig/aireceptionist

## Overview

AI Receptionist is a self-hosted, multi-business phone agent: a caller enters through telephony, has a voice conversation, and may receive answers, a transfer, a message-taking flow, an intake, or an appointment booking. The agent coordinates configuration, prompts, and voice authentication; call lifecycle handling captures transcripts and recordings and dispatches follow-up messages. The README documents Realtime voice, FAQs, transfers, after-hours behavior, and SIP integrations. Source-index references support the principal internal links; unsampled subsystems are included where documented, with uncertain wiring omitted.

Main entry points: [`receptionist/agent.py`](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/agent.py) (Receptionist agent), [`receptionist/lifecycle.py`](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/lifecycle.py) (Call lifecycle), [`receptionist/messaging/dispatcher.py`](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/messaging/dispatcher.py) (Message dispatcher), [`receptionist/booking/booking.py`](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/booking/booking.py) (Appointment booking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Voice conversation"]
  node_agent["Receptionist agent<br/>[agent.py]"]
  node_prompts["Prompts and FAQs<br/>[prompts.py]"]
  node_voice_auth["Voice authentication<br/>[voice_auth.py]"]
end

subgraph group_booking_intake["Booking and intake"]
  node_booking["Appointment booking<br/>[booking.py]"]
  node_availability["Availability lookup<br/>[availability.py]"]
  node_intake_capture["Keypad intake capture<br/>[dtmf_capture.py]"]
  node_intake_storage[("Intake storage<br/>[storage.py]")]
  node_info_packets["Information packets<br/>[info_packets.py]"]
end

subgraph group_call_records["Call records"]
  node_lifecycle["Call lifecycle<br/>[lifecycle.py]"]
  node_transcript_capture["Transcript capture<br/>[capture.py]"]
  node_transcript_writer["Transcript writer<br/>[writer.py]"]
  node_recording["Recording egress<br/>[egress.py]"]
  node_retention["Retention sweeper<br/>[sweeper.py]"]
end

subgraph group_delivery["Message delivery"]
  node_dispatcher["Message dispatcher<br/>[dispatcher.py]"]
  node_file_channel[("File channel<br/>[file.py]")]
  node_webhook_channel["Webhook channel<br/>[webhook.py]"]
  node_email_channel["Email channel<br/>[email.py]"]
  node_email_templates["Email templates<br/>[templates.py]"]
  node_email_sender["Email sender<br/>[sender.py]"]
end

subgraph group_configuration["Configuration"]
  node_config["Business configuration<br/>[config.py]"]
end

node_caller(("Caller"))
node_telephony{{"SIP / LiveKit"}}
node_realtime{{"OpenAI Realtime"}}
node_calendar{{"Google Calendar"}}
node_webhook_service{{"Configured webhook"}}

node_caller -->|"calls"| node_telephony
node_telephony -->|"routes calls"| node_agent
node_agent -->|"voice conversation"| node_realtime
node_agent -->|"loads settings"| node_config
node_agent -->|"uses prompts"| node_prompts
node_agent -->|"gets credentials"| node_voice_auth
node_agent -->|"starts lifecycle"| node_lifecycle
node_agent -->|"checks availability"| node_availability
node_agent -->|"books appointments"| node_booking
node_agent -->|"captures keypad input"| node_intake_capture
node_agent -->|"stores intake"| node_intake_storage
node_agent -->|"dispatches messages"| node_dispatcher
node_agent -->|"sends information"| node_info_packets
node_booking -.->|"creates events"| node_calendar
node_booking -.->|"checks slots"| node_availability
node_lifecycle -->|"captures transcript"| node_transcript_capture
node_lifecycle -->|"writes transcript"| node_transcript_writer
node_lifecycle -->|"starts recording"| node_recording
node_lifecycle -->|"dispatches call updates"| node_dispatcher
node_lifecycle -->|"uses settings"| node_config
node_retention -.->|"reads policy"| node_config
node_dispatcher -->|"dispatches to"| node_file_channel
node_dispatcher -->|"dispatches to"| node_webhook_channel
node_dispatcher -->|"dispatches to"| node_email_channel
node_webhook_channel -->|"posts message"| node_webhook_service
node_email_channel -->|"builds email"| node_email_templates
node_email_channel -->|"sends email"| node_email_sender

click node_agent "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/agent.py"
click node_prompts "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/prompts.py"
click node_voice_auth "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/voice_auth.py"
click node_config "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/config.py"
click node_lifecycle "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/lifecycle.py"
click node_transcript_capture "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/transcript/capture.py"
click node_transcript_writer "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/transcript/writer.py"
click node_recording "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/recording/egress.py"
click node_retention "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/retention/sweeper.py"
click node_booking "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/booking/booking.py"
click node_availability "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/booking/availability.py"
click node_intake_capture "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/intakes/dtmf_capture.py"
click node_intake_storage "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/intakes/storage.py"
click node_info_packets "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/info_packets.py"
click node_dispatcher "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/messaging/dispatcher.py"
click node_file_channel "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/messaging/channels/file.py"
click node_webhook_channel "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/messaging/channels/webhook.py"
click node_email_channel "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/messaging/channels/email.py"
click node_email_templates "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/email/templates.py"
click node_email_sender "https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/email/sender.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_agent,node_prompts,node_voice_auth toneBlue
class node_booking,node_availability,node_intake_capture,node_intake_storage,node_info_packets toneAmber
class node_lifecycle,node_transcript_capture,node_transcript_writer,node_recording,node_retention,node_webhook_service toneMint
class node_dispatcher,node_file_channel,node_webhook_channel,node_email_channel,node_email_templates,node_email_sender toneRose
class node_config,node_caller,node_telephony,node_realtime,node_calendar toneIndigo
```

## Components

### Voice conversation

- [Receptionist agent](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/agent.py): `receptionist/agent.py`
- [Prompts and FAQs](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/prompts.py): `receptionist/prompts.py`
- [Voice authentication](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/voice_auth.py): `receptionist/voice_auth.py`

### Booking and intake

- [Appointment booking](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/booking/booking.py): `receptionist/booking/booking.py`
- [Availability lookup](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/booking/availability.py): `receptionist/booking/availability.py`
- [Keypad intake capture](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/intakes/dtmf_capture.py): `receptionist/intakes/dtmf_capture.py`
- [Intake storage](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/intakes/storage.py): `receptionist/intakes/storage.py`
- [Information packets](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/info_packets.py): `receptionist/info_packets.py`

### Call records

- [Call lifecycle](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/lifecycle.py): `receptionist/lifecycle.py`
- [Transcript capture](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/transcript/capture.py): `receptionist/transcript/capture.py`
- [Transcript writer](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/transcript/writer.py): `receptionist/transcript/writer.py`
- [Recording egress](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/recording/egress.py): `receptionist/recording/egress.py`
- [Retention sweeper](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/retention/sweeper.py): `receptionist/retention/sweeper.py`

### Message delivery

- [Message dispatcher](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/messaging/dispatcher.py): `receptionist/messaging/dispatcher.py`
- [File channel](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/messaging/channels/file.py): `receptionist/messaging/channels/file.py`
- [Webhook channel](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/messaging/channels/webhook.py): `receptionist/messaging/channels/webhook.py`
- [Email channel](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/messaging/channels/email.py): `receptionist/messaging/channels/email.py`
- [Email templates](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/email/templates.py): `receptionist/email/templates.py`
- [Email sender](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/email/sender.py): `receptionist/email/sender.py`

### Configuration

- [Business configuration](https://github.com/kirklandsig/aireceptionist/blob/main/receptionist/config.py): `receptionist/config.py`

### Other components

- **Caller**
- **SIP / LiveKit**
- **OpenAI Realtime**
- **Google Calendar**
- **Configured webhook**

## Connections

- Caller → SIP / LiveKit: calls
- SIP / LiveKit → Receptionist agent: routes calls
- Receptionist agent → OpenAI Realtime: voice conversation
- Receptionist agent → Business configuration: loads settings (evidence: `receptionist/agent.py`)
- Receptionist agent → Prompts and FAQs: uses prompts (evidence: `receptionist/agent.py`)
- Receptionist agent → Voice authentication: gets credentials (evidence: `receptionist/agent.py`)
- Receptionist agent → Call lifecycle: starts lifecycle (evidence: `receptionist/agent.py`)
- Receptionist agent → Availability lookup: checks availability (evidence: `receptionist/agent.py`)
- Receptionist agent → Appointment booking: books appointments (evidence: `receptionist/agent.py`)
- Receptionist agent → Keypad intake capture: captures keypad input (evidence: `receptionist/agent.py`)
- Receptionist agent → Intake storage: stores intake (evidence: `receptionist/agent.py`)
- Receptionist agent → Message dispatcher: dispatches messages (evidence: `receptionist/agent.py`)
- Receptionist agent → Information packets: sends information (evidence: `receptionist/agent.py`)
- Appointment booking → Google Calendar: creates events
- Appointment booking → Availability lookup: checks slots
- Call lifecycle → Transcript capture: captures transcript (evidence: `receptionist/lifecycle.py`)
- Call lifecycle → Transcript writer: writes transcript (evidence: `receptionist/lifecycle.py`)
- Call lifecycle → Recording egress: starts recording (evidence: `receptionist/lifecycle.py`)
- Call lifecycle → Message dispatcher: dispatches call updates (evidence: `receptionist/lifecycle.py`)
- Call lifecycle → Business configuration: uses settings (evidence: `receptionist/lifecycle.py`)
- Retention sweeper → Business configuration: reads policy (evidence: `receptionist/retention/sweeper.py`)
- Message dispatcher → File channel: dispatches to (evidence: `receptionist/messaging/dispatcher.py`)
- Message dispatcher → Webhook channel: dispatches to (evidence: `receptionist/messaging/dispatcher.py`)
- Message dispatcher → Email channel: dispatches to (evidence: `receptionist/messaging/dispatcher.py`)
- Webhook channel → Configured webhook: posts message (evidence: `receptionist/messaging/channels/webhook.py`)
- Email channel → Email templates: builds email (evidence: `receptionist/messaging/channels/email.py`)
- Email channel → Email sender: sends email (evidence: `receptionist/messaging/channels/email.py`)