# mahadevan-007/voice-agent architecture

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

- Interactive diagram: https://gitdiagram.com/mahadevan-007/voice-agent
- Repository: https://github.com/mahadevan-007/voice-agent

## Overview

VocalKart takes a store owner from access request and approval through OTP verification into a LiveKit voice order, where Raj checks inventory and sends a confirmed order summary by WhatsApp. The graph includes the documented admin, bilingual ordering, pricing/schemes, and frontend call experience. Some frontend-to-backend and telephony wiring is not visible in the excerpts, so those links are omitted or marked unverified.

Main entry points: [`token_server.py`](https://github.com/mahadevan-007/voice-agent/blob/main/token_server.py) (FastAPI service), [`agent.py`](https://github.com/mahadevan-007/voice-agent/blob/main/agent.py) (Raj voice agent), [`crud.py`](https://github.com/mahadevan-007/voice-agent/blob/main/crud.py) (Catalog and request operations), [`whatsapp.py`](https://github.com/mahadevan-007/voice-agent/blob/main/whatsapp.py) (WhatsApp summary sender)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_customer["Storefront"]
  node_landing["Access landing page<br/>[LandingPage.tsx]"]
  node_app["Frontend app<br/>[App.tsx]"]
  node_callui["Call experience<br/>[CallPage.tsx]"]
  node_callcomponents["LiveKit call controls"]
end

subgraph group_access["Access and Approval"]
  node_api["FastAPI service<br/>[token_server.py]"]
  node_admin["Admin approval panel<br/>[admin.py]"]
  node_otp["OTP handling<br/>[otp.py]"]
  node_email["Approval email<br/>[email_service.py]"]
end

subgraph group_voice["Voice Ordering"]
  node_agent["Raj voice agent<br/>[agent.py]"]
  node_prompt["Ordering instructions<br/>[prompt.py]"]
  node_call["Outbound call dispatch<br/>[call.py]"]
end

subgraph group_catalog["Catalog and Data"]
  node_crud["Catalog and request operations<br/>[crud.py]"]
  node_models["Inventory and request models<br/>[models.py]"]
  node_database["Database sessions<br/>[database.py]"]
  node_seed["Product catalog seed<br/>[init_db.py]"]
end

subgraph group_delivery["Order Delivery"]
  node_whatsapp["WhatsApp summary sender<br/>[whatsapp.py]"]
end

node_owner(("Store owner"))
node_sms["Twilio SMS"]
node_livekit["LiveKit voice service"]
node_postgres[("PostgreSQL inventory")]
node_twilio["Twilio WhatsApp"]
node_whatomate["Whatomate fallback"]

node_owner -->|"requests access"| node_landing
node_app -->|"renders"| node_landing
node_landing -->|"polls status"| node_api
node_owner -->|"reviews request"| node_admin
node_api -->|"mounts router"| node_admin
node_api -->|"manages requests"| node_crud
node_api -->|"sends notification"| node_email
node_email -->|"emails approval link"| node_admin
node_api -->|"generates codes"| node_otp
node_api -.->|"sends OTP"| node_sms
node_owner -->|"starts call"| node_callui
node_callui -.->|"uses controls"| node_callcomponents
node_owner -->|"speaks order"| node_livekit
node_call -->|"dispatches agent"| node_livekit
node_livekit -->|"runs agent"| node_agent
node_agent -->|"uses instructions"| node_prompt
node_agent -->|"looks up catalog"| node_crud
node_agent -->|"deducts stock"| node_crud
node_seed -->|"creates products"| node_crud
node_crud -->|"queries models"| node_models
node_models -->|"uses base"| node_database
node_database -.->|"opens sessions"| node_postgres
node_agent -.->|"sends confirmed order"| node_whatsapp
node_whatsapp -.->|"delivers summary"| node_twilio
node_whatsapp -.->|"fallback delivery"| node_whatomate

click node_landing "https://github.com/mahadevan-007/voice-agent/blob/main/frontend/src/pages/LandingPage.tsx"
click node_app "https://github.com/mahadevan-007/voice-agent/blob/main/frontend/src/App.tsx"
click node_callui "https://github.com/mahadevan-007/voice-agent/blob/main/frontend/src/pages/CallPage.tsx"
click node_callcomponents "https://github.com/mahadevan-007/voice-agent/tree/main/frontend/src/components"
click node_api "https://github.com/mahadevan-007/voice-agent/blob/main/token_server.py"
click node_admin "https://github.com/mahadevan-007/voice-agent/blob/main/admin.py"
click node_otp "https://github.com/mahadevan-007/voice-agent/blob/main/otp.py"
click node_email "https://github.com/mahadevan-007/voice-agent/blob/main/email_service.py"
click node_agent "https://github.com/mahadevan-007/voice-agent/blob/main/agent.py"
click node_prompt "https://github.com/mahadevan-007/voice-agent/blob/main/prompt.py"
click node_call "https://github.com/mahadevan-007/voice-agent/blob/main/call.py"
click node_crud "https://github.com/mahadevan-007/voice-agent/blob/main/crud.py"
click node_models "https://github.com/mahadevan-007/voice-agent/blob/main/models.py"
click node_database "https://github.com/mahadevan-007/voice-agent/blob/main/database.py"
click node_seed "https://github.com/mahadevan-007/voice-agent/blob/main/init_db.py"
click node_whatsapp "https://github.com/mahadevan-007/voice-agent/blob/main/whatsapp.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_landing,node_app,node_callui,node_callcomponents toneBlue
class node_api,node_admin,node_otp,node_email,node_postgres toneAmber
class node_agent,node_prompt,node_call toneMint
class node_crud,node_models,node_database,node_seed toneRose
class node_whatsapp,node_owner,node_sms,node_livekit,node_twilio,node_whatomate toneIndigo
```

## Components

### Storefront

- [Access landing page](https://github.com/mahadevan-007/voice-agent/blob/main/frontend/src/pages/LandingPage.tsx): `frontend/src/pages/LandingPage.tsx`
- [Frontend app](https://github.com/mahadevan-007/voice-agent/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Call experience](https://github.com/mahadevan-007/voice-agent/blob/main/frontend/src/pages/CallPage.tsx): `frontend/src/pages/CallPage.tsx`
- [LiveKit call controls](https://github.com/mahadevan-007/voice-agent/tree/main/frontend/src/components): `frontend/src/components`

### Access and Approval

- [FastAPI service](https://github.com/mahadevan-007/voice-agent/blob/main/token_server.py): `token_server.py`
- [Admin approval panel](https://github.com/mahadevan-007/voice-agent/blob/main/admin.py): `admin.py`
- [OTP handling](https://github.com/mahadevan-007/voice-agent/blob/main/otp.py): `otp.py`
- [Approval email](https://github.com/mahadevan-007/voice-agent/blob/main/email_service.py): `email_service.py`

### Voice Ordering

- [Raj voice agent](https://github.com/mahadevan-007/voice-agent/blob/main/agent.py): `agent.py`
- [Ordering instructions](https://github.com/mahadevan-007/voice-agent/blob/main/prompt.py): `prompt.py`
- [Outbound call dispatch](https://github.com/mahadevan-007/voice-agent/blob/main/call.py): `call.py`

### Catalog and Data

- [Catalog and request operations](https://github.com/mahadevan-007/voice-agent/blob/main/crud.py): `crud.py`
- [Inventory and request models](https://github.com/mahadevan-007/voice-agent/blob/main/models.py): `models.py`
- [Database sessions](https://github.com/mahadevan-007/voice-agent/blob/main/database.py): `database.py`
- [Product catalog seed](https://github.com/mahadevan-007/voice-agent/blob/main/init_db.py): `init_db.py`

### Order Delivery

- [WhatsApp summary sender](https://github.com/mahadevan-007/voice-agent/blob/main/whatsapp.py): `whatsapp.py`

### Other components

- **Store owner**
- **Twilio SMS**
- **LiveKit voice service**
- **PostgreSQL inventory**
- **Twilio WhatsApp**
- **Whatomate fallback**

## Connections

- Store owner → Access landing page: requests access
- Frontend app → Access landing page: renders (evidence: `frontend/src/App.tsx`)
- Access landing page → FastAPI service: polls status (evidence: `frontend/src/pages/LandingPage.tsx`)
- Store owner → Admin approval panel: reviews request
- FastAPI service → Admin approval panel: mounts router (evidence: `token_server.py`)
- FastAPI service → Catalog and request operations: manages requests (evidence: `token_server.py`)
- FastAPI service → Approval email: sends notification (evidence: `token_server.py`)
- Approval email → Admin approval panel: emails approval link (evidence: `email_service.py`)
- FastAPI service → OTP handling: generates codes (evidence: `token_server.py`)
- FastAPI service → Twilio SMS: sends OTP
- Store owner → Call experience: starts call
- Call experience → LiveKit call controls: uses controls
- Store owner → LiveKit voice service: speaks order
- Outbound call dispatch → LiveKit voice service: dispatches agent
- LiveKit voice service → Raj voice agent: runs agent
- Raj voice agent → Ordering instructions: uses instructions (evidence: `agent.py`)
- Raj voice agent → Catalog and request operations: looks up catalog (evidence: `agent.py`)
- Raj voice agent → Catalog and request operations: deducts stock (evidence: `agent.py`)
- Product catalog seed → Catalog and request operations: creates products (evidence: `init_db.py`)
- Catalog and request operations → Inventory and request models: queries models (evidence: `crud.py`)
- Inventory and request models → Database sessions: uses base (evidence: `models.py`)
- Database sessions → PostgreSQL inventory: opens sessions
- Raj voice agent → WhatsApp summary sender: sends confirmed order (evidence: `agent.py`)
- WhatsApp summary sender → Twilio WhatsApp: delivers summary
- WhatsApp summary sender → Whatomate fallback: fallback delivery
