# gaxxrav/smart-reserve architecture

> Architecture diagram of the GitHub repository gaxxrav/smart-reserve, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gaxxrav/smart-reserve
- Repository: https://github.com/gaxxrav/smart-reserve

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External services
    subgraph "External Services"
        TW["Twilio Voice API"]:::external
        DF["Dialogflow CX"]:::external
        GM["Google Gemini AI"]:::external
    end

    %% Backend service
    subgraph "Backend Service"
        FAST["FastAPI (main.py)"]:::backend
        D_UTIL["dialogflow_utils.py"]:::backend
        G_UTIL["gemini_utils.py"]:::backend
    end

    %% Database
    subgraph "Database"
        DB["SQLite (db.py)"]:::db
    end

    %% Local testing frontend
    subgraph "Local Testing Frontend"
        FE["simple_frontend.html<br/>serve_frontend.py"]:::test
    end

    %% Config
    ENV[".env (env.example)"]:::note

    %% Data flow
    TW -->|"Incoming Call\nPOST /twilio/voice"| FAST
    TW -->|"STT → text"| FAST
    FAST -->|"detect_intent(text)"| D_UTIL
    D_UTIL -->|"intent + parameters"| FAST
    FAST -->|"generate_response(intent, params)"| G_UTIL
    G_UTIL -->|"response text"| FAST
    FAST -->|"CRUD operations"| DB
    FAST -->|"ResponseText → TTS"| TW

    %% Management and test endpoints
    FE -.->|"GET/POST /bookings\n/test/dialogflow\n/test/gemini\n/health"| FAST

    %% Configuration injection
    ENV -.-> FAST

    %% Styling
    classDef external fill:#AED6F1,stroke:#2E86C1,color:#1B4F72;
    classDef backend fill:#ABEBC6,stroke:#28B463,color:#186A3B;
    classDef db fill:#F9E79F,stroke:#B7950B,color:#7D6608;
    classDef test fill:#D5D8DC,stroke:#7B7D7D,color:#1C2833,stroke-dasharray: 5 5;
    classDef note fill:#F2F3F4,stroke:#BFC9CA,color:#566573,stroke-dasharray: 2 2;
```
