# wcr-karan/ai-voice-agent architecture

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

- Interactive diagram: https://gitdiagram.com/wcr-karan/ai-voice-agent
- Repository: https://github.com/wcr-karan/ai-voice-agent

## Overview

1. **What this repository is**
   - This is the backend and conversation-configuration layer for a voice receptionist, not a general web app.
   - The runtime center is a **FastAPI** service that RetellAI calls during live conversations and after calls complete.

2. **Top-level architecture**
   - The system has three main runtime boundaries:
     - **RetellAI** for the voice conversation state machine and live call orchestration.
     - **FastAPI backend** for business actions like booking, FAQ lookup, availability checks, transfers, and webhook handling.
     - **Google Sheets + SMTP** as the persistence and notification layers.
   - The backend is the integration hub between voice events and external clinic systems.

3. **Request and event flow**
   - During a call, RetellAI uses function nodes to call backend endpoints such as booking, availability, FAQ, and transfer.
   - After the call, RetellAI sends webhook events to the backend for logging and post-call processing.
   - Booking requests flow from the voice agent into FastAPI, then into validation/business logic, then into Google Sheets, and finally into email confirmation delivery.

4. **API layer**
   - `app/api/` contains the route handlers and is the main HTTP boundary.
   - The exposed endpoints map directly to the voice-agent use cases:
     - booking
     - availability lookup
     - FAQ matching
     - human transfer
     - webhook ingestion
   - `app/main.py` wires these routes into the FastAPI app, along with health/root endpoints and global app behavior.

5. **Service layer**
   - `app/services/` holds the real business logic and is the main domain boundary.
   - `booking_service.py` handles booking rules, conflict checks, and appointment creation.
   - `faq_service.py` performs FAQ lookup and matching behavior.
   - `sheets_service.py` is the data-access layer for Google Sheets reads/writes.
   - `email_service.py` sends confirmation emails asynchronously so the voice flow stays responsive.

6. **Data model boundary**
   - `app/models/` defines the Pydantic schemas for request/response contracts.
   - These models separate external payloads from internal logic for appointments, FAQs, and webhook events.
   - This is important because Retell payloads and function-node inputs are validated before they reach the business layer.

7. **Security and webhook trust boundary**
   - `app/middleware/signature.py` verifies incoming Retell webhooks with HMAC-SHA256.
   - That makes the webhook endpoint a guarded boundary rather than a public write surface.
   - In architecture terms, only authenticated Retell-originated post-call events should be able to mutate logging state.

8. **Persistence and operational data**
   - Google Sheets is used as the system of record for appointments, FAQs, and call logs.
   - This is a lightweight, operator-editable data layer rather than a traditional database.
   - Because Sheets is external and rate-limited, the service layer likely minimizes writes and uses read-before-write validation for conflicts.

9. **Notification subsystem**
   - `templates/confirmation_email.html` is the email presentation layer.
   - `email_service.py` renders/sends confirmations using SMTP after a successful booking.
   - The README indicates this is done asynchronously via FastAPI background tasks so call responses remain fast enough for Retell.

10. **RetellAI assets**
   - The `retell/` directory is not application code; it is conversation configuration.
   - `agent_config.json` and `conversation_flow.json` define the deterministic call flow that drives the voice experience.
   - Prompt fragments under `retell/prompts/` support the conversational nodes for greeting, FAQ handling, booking, fallback, and closing.

11. **Utility and cross-cutting concerns**
   - `app/utils/datetime_helpers.py` centralizes slot generation and spoken-date/time parsing.
   - `app/utils/logger.py` provides structured logging for operational visibility.
   - `app/config.py` is the environment/configuration boundary, likely holding Retell, Google Sheets, and SMTP settings.

12. **Scripts and bootstrap tooling**
   - `scripts/setup_google_sheets.py` initializes the Sheets schema and headers.
   - `scripts/seed_faq_data.py` populates FAQ content for the agent.
   - `scripts/demo_simulation.py` is a local integration simulator that exercises the backend flow without a live phone call.
   - These scripts support deployment and data setup rather than runtime traffic.

13. **Testing strategy**
   - `tests/` is organized around the same system boundaries as production code.
   - There are tests for availability, booking, FAQ, and webhook behavior, which implies the repo treats those as the core contracts.
   - This suggests the architecture is designed for service-layer testing without depending on live Retell or Google Sheets during every test.

14. **Operational/deployment shape**
   - The repo is meant to run as a single FastAPI service deployed behind HTTPS.
   - The docs and environment files show that production depends on external credentials for Retell, Google Sheets, and SMTP.
   - The architecture therefore centers on stateless API processing, with externalized state and integrations.

15. **What to draw in an architecture diagram**
   - Draw RetellAI as the conversation orchestrator on one side.
   - Draw FastAPI in the middle, split into API routes, services, models, and middleware.
   - Draw Google Sheets and SMTP as external dependencies on the other side.
   - Show booking and webhook flows as the two most important paths, with FAQ and transfer as secondary function-node actions.

Main entry points: [`app/main.py`](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/main.py) (App entry), [`app/services/booking_service.py`](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/services/booking_service.py) (Booking service), [`retell/conversation_flow.json`](https://github.com/wcr-karan/ai-voice-agent/blob/main/retell/conversation_flow.json) (Conversation flow), [`app/api/webhook.py`](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/api/webhook.py) (Webhook API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_retell["RetellAI"]
  node_retell_agent_config["Agent config<br/>retell config<br/>[agent_config.json]"]
  node_retell_flow["Conversation flow<br/>retell flow"]
  node_retell_prompts["Prompt pack<br/>retell prompts"]
end

subgraph group_backend["FastAPI backend"]
  node_main_app["App entry<br/>fastapi bootstrap<br/>[main.py]"]
  node_api_booking["Booking API<br/>route handler<br/>[booking.py]"]
  node_api_availability["Availability API<br/>route handler<br/>[availability.py]"]
  node_api_faq["FAQ API<br/>route handler<br/>[faq.py]"]
  node_api_transfer["Transfer API<br/>route handler<br/>[transfer.py]"]
  node_api_webhook["Webhook API<br/>route handler<br/>[webhook.py]"]
  node_signature_mw["Signature check<br/>webhook middleware<br/>[signature.py]"]
  node_booking_service["Booking service<br/>domain service<br/>[booking_service.py]"]
  node_faq_service["FAQ service<br/>domain service<br/>[faq_service.py]"]
  node_sheets_service[("Sheets service<br/>data access<br/>[sheets_service.py]")]
  node_email_service["Email service<br/>notification service<br/>[email_service.py]"]
  node_appointment_models["Appointment models<br/>pydantic schemas<br/>[appointment.py]"]
  node_faq_models["FAQ models<br/>pydantic schemas<br/>[faq.py]"]
  node_webhook_models["Webhook models<br/>pydantic schemas<br/>[webhook_event.py]"]
  node_config["Config<br/>[config.py]"]
end

subgraph group_external["External systems"]
  node_google_sheets[("Google Sheets<br/>external store")]
  node_smtp["SMTP<br/>external mail"]
end

subgraph group_support["Support"]
  node_datetime_helpers["Datetime helpers"]
  node_logger["Logger<br/>[logger.py]"]
  node_email_template["Email template<br/>html template"]
  node_setup_sheets["Sheets setup<br/>bootstrap script"]
  node_seed_faq["Seed FAQ<br/>bootstrap script<br/>[seed_faq_data.py]"]
  node_demo_sim["Demo simulation<br/>integration script<br/>[demo_simulation.py]"]
end

node_retell_flow -->|"book"| node_api_booking
node_retell_flow -->|"availability"| node_api_availability
node_retell_flow -->|"faq"| node_api_faq
node_retell_flow -->|"transfer"| node_api_transfer
node_retell_agent_config -->|"drives"| node_retell_flow
node_retell_prompts -.->|"supports"| node_retell_flow
node_main_app -->|"mounts"| node_api_booking
node_main_app -->|"mounts"| node_api_availability
node_main_app -->|"mounts"| node_api_faq
node_main_app -->|"mounts"| node_api_transfer
node_main_app -->|"mounts"| node_api_webhook
node_api_booking -->|"uses"| node_booking_service
node_api_availability -->|"uses"| node_booking_service
node_api_faq -->|"uses"| node_faq_service
node_api_webhook -->|"protects"| node_signature_mw
node_api_webhook -->|"validates"| node_webhook_models
node_booking_service -->|"validates"| node_appointment_models
node_booking_service -->|"writes"| node_sheets_service
node_booking_service -->|"notifies"| node_email_service
node_faq_service -->|"uses"| node_faq_models
node_sheets_service -->|"reads/writes"| node_google_sheets
node_email_service -->|"sends"| node_smtp
node_email_service -->|"renders"| node_email_template
node_booking_service -.->|"uses"| node_datetime_helpers
node_api_webhook -.->|"logs"| node_logger
node_main_app -->|"loads"| node_config
node_setup_sheets -.->|"initializes"| node_google_sheets
node_seed_faq -.->|"seeds"| node_google_sheets
node_demo_sim -.->|"exercises"| node_api_booking
node_demo_sim -.->|"exercises"| node_api_webhook

click node_retell_agent_config "https://github.com/wcr-karan/ai-voice-agent/blob/main/retell/agent_config.json"
click node_retell_flow "https://github.com/wcr-karan/ai-voice-agent/blob/main/retell/conversation_flow.json"
click node_retell_prompts "https://github.com/wcr-karan/ai-voice-agent/tree/main/retell/prompts"
click node_main_app "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/main.py"
click node_api_booking "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/api/booking.py"
click node_api_availability "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/api/availability.py"
click node_api_faq "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/api/faq.py"
click node_api_transfer "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/api/transfer.py"
click node_api_webhook "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/api/webhook.py"
click node_signature_mw "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/middleware/signature.py"
click node_booking_service "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/services/booking_service.py"
click node_faq_service "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/services/faq_service.py"
click node_sheets_service "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/services/sheets_service.py"
click node_email_service "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/services/email_service.py"
click node_appointment_models "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/models/appointment.py"
click node_faq_models "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/models/faq.py"
click node_webhook_models "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/models/webhook_event.py"
click node_config "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/config.py"
click node_datetime_helpers "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/utils/datetime_helpers.py"
click node_logger "https://github.com/wcr-karan/ai-voice-agent/blob/main/app/utils/logger.py"
click node_email_template "https://github.com/wcr-karan/ai-voice-agent/blob/main/templates/confirmation_email.html"
click node_setup_sheets "https://github.com/wcr-karan/ai-voice-agent/blob/main/scripts/setup_google_sheets.py"
click node_seed_faq "https://github.com/wcr-karan/ai-voice-agent/blob/main/scripts/seed_faq_data.py"
click node_demo_sim "https://github.com/wcr-karan/ai-voice-agent/blob/main/scripts/demo_simulation.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_retell_agent_config,node_retell_flow,node_retell_prompts toneBlue
class node_main_app,node_api_booking,node_api_availability,node_api_faq,node_api_transfer,node_api_webhook,node_signature_mw,node_booking_service,node_faq_service,node_sheets_service,node_email_service,node_appointment_models,node_faq_models,node_webhook_models,node_config toneAmber
class node_google_sheets,node_smtp toneMint
class node_datetime_helpers,node_logger,node_email_template,node_setup_sheets,node_seed_faq,node_demo_sim toneRose
```

## Components

### RetellAI

Conversation flow and prompt configuration for live calls

- [Agent config](https://github.com/wcr-karan/ai-voice-agent/blob/main/retell/agent_config.json): retell config · Main RetellAI agent configuration for conversation behavior · `retell/agent_config.json`
- [Conversation flow](https://github.com/wcr-karan/ai-voice-agent/blob/main/retell/conversation_flow.json): retell flow · Deterministic call flow used by the voice agent · `retell/conversation_flow.json`
- [Prompt pack](https://github.com/wcr-karan/ai-voice-agent/tree/main/retell/prompts): retell prompts · Prompt fragments for greeting, booking, FAQ, fallback, and closing · `retell/prompts`

### FastAPI backend

HTTP API, middleware, models, and business services

- [App entry](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/main.py): fastapi bootstrap · FastAPI application wiring and global startup behavior · `app/main.py`
- [Booking API](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/api/booking.py): route handler · Booking endpoint for appointment creation requests · `app/api/booking.py`
- [Availability API](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/api/availability.py): route handler · Availability lookup endpoint for open slots and conflicts · `app/api/availability.py`
- [FAQ API](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/api/faq.py): route handler · FAQ matching endpoint for conversational lookup · `app/api/faq.py`
- [Transfer API](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/api/transfer.py): route handler · Human transfer endpoint for escalation handling · `app/api/transfer.py`
- [Webhook API](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/api/webhook.py): route handler · Retell post-call webhook ingestion boundary · `app/api/webhook.py`
- [Signature check](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/middleware/signature.py): webhook middleware · HMAC verification for trusted Retell webhook events · `app/middleware/signature.py`
- [Booking service](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/services/booking_service.py): domain service · Booking rules, conflict checks, and appointment creation · `app/services/booking_service.py`
- [FAQ service](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/services/faq_service.py): domain service · FAQ matching and answer selection logic · `app/services/faq_service.py`
- [Sheets service](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/services/sheets_service.py): data access · Google Sheets read/write layer for appointments, FAQs, and logs · `app/services/sheets_service.py`
- [Email service](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/services/email_service.py): notification service · Asynchronous confirmation email delivery via SMTP · `app/services/email_service.py`
- [Appointment models](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/models/appointment.py): pydantic schemas · Request and response contracts for bookings and appointments · `app/models/appointment.py`
- [FAQ models](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/models/faq.py): pydantic schemas · Schemas for FAQ payloads and matching results · `app/models/faq.py`
- [Webhook models](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/models/webhook_event.py): pydantic schemas · Schemas for inbound call events and post-call payloads · `app/models/webhook_event.py`
- [Config](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/config.py): environment config · Application settings for Retell, Sheets, SMTP, and runtime behavior · `app/config.py`

### External systems

Persistence and notification dependencies outside the app

- **Google Sheets**: external store · System of record for appointments, FAQs, and call logs
- **SMTP**: external mail · Outbound email delivery service for confirmations

### Support

Utility, scripts, docs, and templates that support the runtime

- [Datetime helpers](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/utils/datetime_helpers.py): utility · Slot generation and spoken date/time parsing helpers · `app/utils/datetime_helpers.py`
- [Logger](https://github.com/wcr-karan/ai-voice-agent/blob/main/app/utils/logger.py): utility · Structured logging for operational visibility · `app/utils/logger.py`
- [Email template](https://github.com/wcr-karan/ai-voice-agent/blob/main/templates/confirmation_email.html): html template · Confirmation email presentation layer · `templates/confirmation_email.html`
- [Sheets setup](https://github.com/wcr-karan/ai-voice-agent/blob/main/scripts/setup_google_sheets.py): bootstrap script · Initializes Google Sheets schema and headers · `scripts/setup_google_sheets.py`
- [Seed FAQ](https://github.com/wcr-karan/ai-voice-agent/blob/main/scripts/seed_faq_data.py): bootstrap script · Populates FAQ content for the agent · `scripts/seed_faq_data.py`
- [Demo simulation](https://github.com/wcr-karan/ai-voice-agent/blob/main/scripts/demo_simulation.py): integration script · Local end-to-end simulation of the backend flow · `scripts/demo_simulation.py`

## Connections

- Conversation flow → Booking API: book · Retell function node calls booking endpoint
- Conversation flow → Availability API: availability · Retell function node checks open slots
- Conversation flow → FAQ API: faq · Retell function node requests FAQ lookup
- Conversation flow → Transfer API: transfer · Retell function node requests escalation
- Agent config → Conversation flow: drives · Agent configuration selects the conversation flow
- Prompt pack → Conversation flow: supports · Prompt fragments supply conversational content
- App entry → Booking API: mounts · FastAPI app registers booking routes
- App entry → Availability API: mounts · FastAPI app registers availability routes
- App entry → FAQ API: mounts · FastAPI app registers FAQ routes
- App entry → Transfer API: mounts · FastAPI app registers transfer routes
- App entry → Webhook API: mounts · FastAPI app registers webhook routes
- Booking API → Booking service: uses · Booking route delegates business rules
- Availability API → Booking service: uses · Availability route reuses booking logic for conflicts and slots
- FAQ API → FAQ service: uses · FAQ route delegates matching logic
- Webhook API → Signature check: protects · Webhook ingestion is guarded by signature verification
- Webhook API → Webhook models: validates · Webhook payloads are validated against schemas
- Booking service → Appointment models: validates · Booking requests are normalized through schemas
- Booking service → Sheets service: writes · Successful bookings are persisted to Sheets
- Booking service → Email service: notifies · Booking completion triggers confirmation email
- FAQ service → FAQ models: uses · FAQ data and responses are schema-driven
- Sheets service → Google Sheets: reads/writes · Persistent state lives in Google Sheets
- Email service → SMTP: sends · Confirmation emails are delivered through SMTP
- Email service → Email template: renders · Email content uses the confirmation template
- Booking service → Datetime helpers: uses · Date and time parsing supports slot selection
- Webhook API → Logger: logs · Webhook events are recorded for operations
- App entry → Config: loads · App startup reads environment configuration
- Sheets setup → Google Sheets: initializes · Bootstrap script prepares the Sheets schema
- Seed FAQ → Google Sheets: seeds · FAQ content is written into Sheets
- Demo simulation → Booking API: exercises · Simulation drives the booking path
- Demo simulation → Webhook API: exercises · Simulation drives webhook ingestion
