How wcr-karan/ai-voice-agent works
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: main.py App entry · booking_service.py Booking service · conversation_flow.json Conversation flow · webhook.py Webhook API
Components 26
RetellAI
Conversation flow and prompt configuration for live calls
- Agent config · Main RetellAI agent configuration for conversation behavior
retell/agent_config.json - Conversation flow · Deterministic call flow used by the voice agent
retell/conversation_flow.json - Prompt pack · Prompt fragments for greeting, booking, FAQ, fallback, and closing
retell/prompts
FastAPI backend
HTTP API, middleware, models, and business services
- App entry · FastAPI application wiring and global startup behavior
app/main.py - Booking API · Booking endpoint for appointment creation requests
app/api/booking.py - Availability API · Availability lookup endpoint for open slots and conflicts
app/api/availability.py - FAQ API · FAQ matching endpoint for conversational lookup
app/api/faq.py - Transfer API · Human transfer endpoint for escalation handling
app/api/transfer.py - Webhook API · Retell post-call webhook ingestion boundary
app/api/webhook.py - Signature check · HMAC verification for trusted Retell webhook events
app/middleware/signature.py - Booking service · Booking rules, conflict checks, and appointment creation
app/services/booking_service.py - FAQ service · FAQ matching and answer selection logic
app/services/faq_service.py - Sheets service · Google Sheets read/write layer for appointments, FAQs, and logs
app/services/sheets_service.py - Email service · Asynchronous confirmation email delivery via SMTP
app/services/email_service.py - Appointment models · Request and response contracts for bookings and appointments
app/models/appointment.py - FAQ models · Schemas for FAQ payloads and matching results
app/models/faq.py - Webhook models · Schemas for inbound call events and post-call payloads
app/models/webhook_event.py - Config · Application settings for Retell, Sheets, SMTP, and runtime behavior
app/config.py
External systems
Persistence and notification dependencies outside the app
- Google Sheets · System of record for appointments, FAQs, and call logs
- SMTP · Outbound email delivery service for confirmations
Support
Utility, scripts, docs, and templates that support the runtime
- Datetime helpers · Slot generation and spoken date/time parsing helpers
app/utils/datetime_helpers.py - Logger · Structured logging for operational visibility
app/utils/logger.py - Email template · Confirmation email presentation layer
templates/confirmation_email.html - Sheets setup · Initializes Google Sheets schema and headers
scripts/setup_google_sheets.py - Seed FAQ · Populates FAQ content for the agent
scripts/seed_faq_data.py - Demo simulation · Local end-to-end simulation of the backend flow
scripts/demo_simulation.py
Connections 30
- 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