# sadman-rahman135/voice-agent architecture

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

- Interactive diagram: https://gitdiagram.com/sadman-rahman135/voice-agent
- Repository: https://github.com/sadman-rahman135/voice-agent

## Overview

CallPilot is a browser-based AI receptionist backed by a FastAPI business API, with a staff dashboard and a simulated-only outbound reminder system. A caller starts a voice session, speaks with the LiveKit voice worker, and the worker requests business actions through the API; the API enforces verification and shop rules and persists results. Staff can review calls and manage operations in the dashboard. The README documents the principal runtime connections; the sampled source also confirms API routing, tool authentication, booking calls and worker session handling. Other unsampled capabilities are represented by their exact enclosing directories.

Main entry points: [`backend/app/main.py`](https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/api/internal`](https://github.com/sadman-rahman135/voice-agent/tree/main/backend/app/api/internal) (Receptionist tools), [`backend/app/db/session.py`](https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/db/session.py) (Postgres), [`frontend/app/dashboard`](https://github.com/sadman-rahman135/voice-agent/tree/main/frontend/app/dashboard) (Staff dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_voice["Voice experience"]
  node_talk["Talk experience<br/>[TalkExperience.tsx]"]
  node_voice_worker["Voice worker<br/>[main.py]"]
  node_agent_behavior["Agent behavior<br/>[agents.py]"]
end

subgraph group_api["Business API"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_tool_auth["Tool authentication<br/>[deps.py]"]
  node_internal_tools["Receptionist tools"]
  node_staff_routes["Staff routes"]
end

subgraph group_domain["Business operations"]
  node_booking["Appointments<br/>[booking.py]"]
  node_verification["Identity verification<br/>[verification.py]"]
  node_call_lifecycle["Call lifecycle<br/>[call_lifecycle.py]"]
  node_knowledge["Knowledge answers"]
  node_persistence[("Postgres<br/>[session.py]")]
end

subgraph group_staff["Staff dashboard"]
  node_dashboard_ui["Staff dashboard"]
  node_staff_auth["Staff sign-in<br/>[auth.py]"]
  node_dashboard_data["Dashboard data<br/>[dashboard.py]"]
  node_live_calls["Live call oversight<br/>[live_calls.py]"]
end

subgraph group_outbound["Outbound reminders"]
  node_outbound_scheduler["Reminder scheduler<br/>[scheduler.py]"]
  node_outbound_jobs["Reminder jobs<br/>[jobs.py]"]
  node_eligibility["Calling eligibility<br/>[eligibility.py]"]
  node_sim_phone["Simulated phone<br/>[SimPhone.tsx]"]
end

node_caller(("Browser caller"))
node_livekit["LiveKit rooms"]

node_caller -->|"speaks through"| node_talk
node_talk -->|"starts session"| node_api_app
node_talk -->|"joins room"| node_livekit
node_livekit -->|"dispatches worker"| node_voice_worker
node_voice_worker -->|"requests tools"| node_api_app
node_voice_worker -->|"runs agent"| node_agent_behavior
node_api_app -->|"registers routes"| node_internal_tools
node_api_app -->|"registers routes"| node_staff_routes
node_internal_tools -->|"authenticates requests"| node_tool_auth
node_internal_tools -->|"calls booking logic"| node_booking
node_internal_tools -->|"checks identity"| node_verification
node_internal_tools -->|"requests answers"| node_knowledge
node_api_app -->|"configures sessions"| node_persistence
node_booking -->|"stores appointments"| node_persistence
node_call_lifecycle -->|"stores call records"| node_persistence
node_dashboard_ui -->|"signs in through"| node_staff_auth
node_dashboard_ui -->|"loads staff data"| node_api_app
node_staff_routes -->|"loads dashboard data"| node_dashboard_data
node_staff_routes -.->|"serves live calls"| node_live_calls
node_dashboard_ui -->|"monitors calls"| node_live_calls
node_outbound_scheduler -.->|"runs jobs"| node_outbound_jobs
node_outbound_jobs -.->|"checks permission"| node_eligibility
node_outbound_scheduler -->|"reads reminders"| node_persistence
node_outbound_scheduler -->|"simulates ringing"| node_sim_phone
node_caller -->|"answers reminder"| node_sim_phone

click node_talk "https://github.com/sadman-rahman135/voice-agent/blob/main/frontend/components/call/TalkExperience.tsx"
click node_voice_worker "https://github.com/sadman-rahman135/voice-agent/blob/main/voice-agent/callpilot_agent/main.py"
click node_agent_behavior "https://github.com/sadman-rahman135/voice-agent/blob/main/voice-agent/callpilot_agent/agents.py"
click node_api_app "https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/main.py"
click node_tool_auth "https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/api/deps.py"
click node_internal_tools "https://github.com/sadman-rahman135/voice-agent/tree/main/backend/app/api/internal"
click node_staff_routes "https://github.com/sadman-rahman135/voice-agent/tree/main/backend/app/api/v1"
click node_booking "https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/services/booking.py"
click node_verification "https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/services/verification.py"
click node_call_lifecycle "https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/services/call_lifecycle.py"
click node_knowledge "https://github.com/sadman-rahman135/voice-agent/tree/main/backend/app/knowledge"
click node_persistence "https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/db/session.py"
click node_dashboard_ui "https://github.com/sadman-rahman135/voice-agent/tree/main/frontend/app/dashboard"
click node_staff_auth "https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/api/v1/auth.py"
click node_dashboard_data "https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/services/dashboard.py"
click node_live_calls "https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/services/live_calls.py"
click node_outbound_scheduler "https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/outbound/scheduler.py"
click node_outbound_jobs "https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/outbound/jobs.py"
click node_eligibility "https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/outbound/eligibility.py"
click node_sim_phone "https://github.com/sadman-rahman135/voice-agent/blob/main/frontend/components/sim/SimPhone.tsx"

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_talk,node_voice_worker,node_agent_behavior,node_caller toneBlue
class node_api_app,node_tool_auth,node_internal_tools,node_staff_routes toneAmber
class node_booking,node_verification,node_call_lifecycle,node_knowledge,node_persistence toneMint
class node_dashboard_ui,node_staff_auth,node_dashboard_data,node_live_calls toneRose
class node_outbound_scheduler,node_outbound_jobs,node_eligibility,node_sim_phone,node_livekit toneIndigo
```

## Components

### Voice experience

- [Talk experience](https://github.com/sadman-rahman135/voice-agent/blob/main/frontend/components/call/TalkExperience.tsx): `frontend/components/call/TalkExperience.tsx`
- [Voice worker](https://github.com/sadman-rahman135/voice-agent/blob/main/voice-agent/callpilot_agent/main.py): `voice-agent/callpilot_agent/main.py`
- [Agent behavior](https://github.com/sadman-rahman135/voice-agent/blob/main/voice-agent/callpilot_agent/agents.py): `voice-agent/callpilot_agent/agents.py`

### Business API

- [FastAPI application](https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/main.py): `backend/app/main.py`
- [Tool authentication](https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`
- [Receptionist tools](https://github.com/sadman-rahman135/voice-agent/tree/main/backend/app/api/internal): `backend/app/api/internal`
- [Staff routes](https://github.com/sadman-rahman135/voice-agent/tree/main/backend/app/api/v1): `backend/app/api/v1`

### Business operations

- [Appointments](https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/services/booking.py): `backend/app/services/booking.py`
- [Identity verification](https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/services/verification.py): `backend/app/services/verification.py`
- [Call lifecycle](https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/services/call_lifecycle.py): `backend/app/services/call_lifecycle.py`
- [Knowledge answers](https://github.com/sadman-rahman135/voice-agent/tree/main/backend/app/knowledge): `backend/app/knowledge`
- [Postgres](https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/db/session.py): `backend/app/db/session.py`

### Staff dashboard

- [Staff dashboard](https://github.com/sadman-rahman135/voice-agent/tree/main/frontend/app/dashboard): `frontend/app/dashboard`
- [Staff sign-in](https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [Dashboard data](https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/services/dashboard.py): `backend/app/services/dashboard.py`
- [Live call oversight](https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/services/live_calls.py): `backend/app/services/live_calls.py`

### Outbound reminders

- [Reminder scheduler](https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/outbound/scheduler.py): `backend/app/outbound/scheduler.py`
- [Reminder jobs](https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/outbound/jobs.py): `backend/app/outbound/jobs.py`
- [Calling eligibility](https://github.com/sadman-rahman135/voice-agent/blob/main/backend/app/outbound/eligibility.py): `backend/app/outbound/eligibility.py`
- [Simulated phone](https://github.com/sadman-rahman135/voice-agent/blob/main/frontend/components/sim/SimPhone.tsx): `frontend/components/sim/SimPhone.tsx`

### Other components

- **Browser caller**
- **LiveKit rooms**

## Connections

- Browser caller → Talk experience: speaks through (evidence: `README.md`)
- Talk experience → FastAPI application: starts session (evidence: `README.md`)
- Talk experience → LiveKit rooms: joins room (evidence: `README.md`)
- LiveKit rooms → Voice worker: dispatches worker (evidence: `README.md`)
- Voice worker → FastAPI application: requests tools (evidence: `README.md`)
- Voice worker → Agent behavior: runs agent (evidence: `voice-agent/callpilot_agent/agents.py`)
- FastAPI application → Receptionist tools: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Staff routes: registers routes (evidence: `backend/app/main.py`)
- Receptionist tools → Tool authentication: authenticates requests (evidence: `backend/app/api/internal/booking.py`)
- Receptionist tools → Appointments: calls booking logic (evidence: `backend/app/api/internal/booking.py`)
- Receptionist tools → Identity verification: checks identity (evidence: `backend/app/api/internal/account.py`)
- Receptionist tools → Knowledge answers: requests answers (evidence: `backend/app/api/internal/public.py`)
- FastAPI application → Postgres: configures sessions (evidence: `backend/app/main.py`)
- Appointments → Postgres: stores appointments (evidence: `README.md`)
- Call lifecycle → Postgres: stores call records (evidence: `README.md`)
- Staff dashboard → Staff sign-in: signs in through (evidence: `README.md`)
- Staff dashboard → FastAPI application: loads staff data (evidence: `README.md`)
- Staff routes → Dashboard data: loads dashboard data (evidence: `backend/app/api/v1/dashboard.py`)
- Staff routes → Live call oversight: serves live calls
- Staff dashboard → Live call oversight: monitors calls (evidence: `README.md`)
- Reminder scheduler → Reminder jobs: runs jobs
- Reminder jobs → Calling eligibility: checks permission
- Reminder scheduler → Postgres: reads reminders (evidence: `README.md`)
- Reminder scheduler → Simulated phone: simulates ringing (evidence: `README.md`)
- Browser caller → Simulated phone: answers reminder (evidence: `README.md`)