How gaxxrav/smart-reserve works
Project Type and Purpose
• SmartReserve is a backend-centric voice assistant service (“AI Voice Assistant for Restaurant Bookings”) rather than a heavy frontend app. Its primary purpose is to handle inbound restaurant calls via Twilio, perform intent recognition with Dialogflow, generate natural language replies via Google Gemini, and manage reservations in an SQLite database.
File Structure Analysis
Top-level files (see README “Project Structure”):
• main.py – FastAPI application, Twilio webhook endpoint
• db.py – Database models & CRUD operations (SQLite)
• dialogflow_utils.py – Integrates with Dialogflow CX API
• gemini_utils.py – Integrates with Google Gemini API
• requirements.txt – Python dependencies
• env.example – Environment variables template
• smartreserve.db – SQLite database (runtime)
No separate “frontend” folder; a small static HTML + serve_frontend.py exists for local testing only.
Key Architecture from README
• Incoming Call (Twilio)
• ↓ Twilio STT
• FastAPI /twilio/voice
• ↓ Dialogflow → detect intent + entities
• ↓ Gemini → generate natural response
• ↓ Save to SQLite (db.py)
• ↓ Twilio TTS
• User hears reply
Main Components
– Twilio Voice API (STT & TTS)
– Google Dialogflow CX
– Google Gemini AI
– FastAPI application (main.py)
· /twilio/voice webhook
· Management endpoints (GET /bookings, POST /bookings, health checks)
· Test endpoints (/test/dialogflow, /test/gemini)
– SQLite via db.py
– simple_frontend.html + serve_frontend.py
Relationships & Data Flow
1. Twilio receives inbound call → invokes FastAPI /twilio/voice (webhook)
2. Twilio STT converts audio → text → passed in webhook payload
3. FastAPI calls dialogflow_utils.detect_intent(text)
4. Dialogflow returns intent & parameters
5. FastAPI calls gemini_utils.generate_response(intent, params)
6. FastAPI optionally writes/reads from SQLite via db.py (e.g., new booking or cancellation)
7. FastAPI returns text reply to Twilio webhook response → Twilio TTS converts to audio → user
Architectural Patterns & Principles
• Single process micro-service (FastAPI) exposing REST/webhook endpoints
• Clear separation of concern:
• dialogflow_utils.py & gemini_utils.py encapsulate external API logic
• db.py encapsulates persistence logic
• main.py orchestrates request handling & routing
• “Pipeline” pattern: streaming through STT → Intent → Response Generation → DB → TTS
• Dependency Injection via environment variables (Twilio credentials, Google service account, Gemini API key, DATABASE_URL)