# ronincodex/voice-agent architecture

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

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

## Overview

Voice Agent is a multilingual phone-calling product with a Next.js dashboard and a FastAPI backend. Its main workflow runs from an outbound-call request or inbound phone call, through Vobiz webhooks and a real-time Pipecat conversation, to persisted call data, recordings, and a post-call summary. Separate dashboard, agent-configuration, compliance, and observability capabilities support that workflow. The backend excerpt and SOURCE INDEX show its main orchestration and dependencies; some subsystem links are documented only at a high level in the README.

Main entry points: [`src/voice_agent/api/server.py`](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/api/server.py) (FastAPI server), [`src/voice_agent/pipeline/agent_pipeline.py`](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/pipeline/agent_pipeline.py) (Voice pipeline), [`src/voice_agent/postcall/summarizer.py`](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/postcall/summarizer.py) (Post-call summary), [`src/voice_agent/db/supabase_client.py`](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/db/supabase_client.py) (Call and transcript store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_dashboard_pages["Dashboard pages"]
  node_dashboard_components["Call views and forms"]
  node_frontend_api["API client<br/>[api.ts]"]
end

subgraph group_api["API and telephony"]
  node_server["FastAPI server<br/>[server.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
  node_telephony["Vobiz adapter<br/>[client.py]"]
  node_call_state["Call tracking<br/>[call_state.py]"]
end

subgraph group_conversation["Conversation pipeline"]
  node_pipeline["Voice pipeline<br/>[agent_pipeline.py]"]
  node_flow_nodes["Conversation stages<br/>[nodes.py]"]
  node_languages["Language prompts<br/>[languages.py]"]
end

subgraph group_data["Persistence and summaries"]
  node_supabase_store["Call and transcript store<br/>[supabase_client.py]"]
  node_agent_config["Agent configuration<br/>[agent_config.py]"]
  node_redis_store["Session state store<br/>[redis_store.py]"]
  node_recordings["Recording storage<br/>[r2_client.py]"]
  node_summary["Post-call summary<br/>[summarizer.py]"]
  node_fallback["Summary fallback<br/>[fallback.py]"]
end

subgraph group_safety["Safety and operations"]
  node_guardrail["Input guardrail<br/>[guardrail.py]"]
  node_validators["Conversation validators<br/>[validators.py]"]
  node_calling_window["Calling window<br/>[calling_window.py]"]
  node_pii["PII masking<br/>[pii.py]"]
  node_audit["Compliance audit<br/>[audit.py]"]
  node_settings["App settings<br/>[settings.py]"]
  node_metrics["Pipeline metrics<br/>[metrics.py]"]
  node_idempotency["Idempotency<br/>[idempotency.py]"]
  node_retry["Retry policies<br/>[retry.py]"]
end

node_user(("Dashboard user"))
node_phone(("Phone caller"))
node_vobiz["Vobiz"]
node_sarvam["Sarvam AI"]
node_groq["Groq"]
node_supabase[("Supabase")]
node_redis[("Upstash Redis")]
node_r2[("Cloudflare R2")]

node_user -->|"uses"| node_dashboard_pages
node_dashboard_pages -.->|"renders"| node_dashboard_components
node_dashboard_pages -.->|"requests data"| node_frontend_api
node_frontend_api -->|"calls API"| node_server
node_phone -->|"calls"| node_vobiz
node_vobiz -->|"webhooks"| node_server
node_server -->|"initiates calls"| node_telephony
node_server -->|"tracks calls"| node_call_state
node_server -->|"starts conversation"| node_pipeline
node_server -->|"validates API data"| node_schemas
node_pipeline -->|"initializes flow"| node_flow_nodes
node_pipeline -->|"loads language config"| node_languages
node_pipeline -->|"uses session state"| node_redis_store
node_pipeline -->|"uses call data"| node_supabase_store
node_pipeline -->|"records events"| node_audit
node_pipeline -->|"collects metrics"| node_metrics
node_pipeline -->|"checks input"| node_guardrail
node_pipeline -->|"validates turns"| node_validators
node_pipeline -->|"uses speech AI"| node_sarvam
node_server -->|"enforces hours"| node_calling_window
node_server -->|"masks transcripts"| node_pii
node_server -->|"reads configuration"| node_agent_config
node_server -->|"reads and writes calls"| node_supabase_store
node_server -->|"stores recordings"| node_recordings
node_recordings -->|"uploads recordings"| node_r2
node_server -->|"generates summary"| node_summary
node_summary -->|"fallback summary"| node_groq
node_summary -->|"summarizes transcript"| node_sarvam
node_summary -->|"uses fallback"| node_fallback
node_supabase_store -->|"persists records"| node_supabase
node_redis_store -->|"stores sessions"| node_redis
node_server -->|"loads configuration"| node_settings
node_telephony -->|"retries requests"| node_retry
node_supabase_store -->|"retries database I/O"| node_retry
node_recordings -->|"retries storage I/O"| node_retry
node_flow_nodes -->|"uses idempotency"| node_idempotency

click node_dashboard_pages "https://github.com/ronincodex/voice-agent/tree/main/frontend/app"
click node_dashboard_components "https://github.com/ronincodex/voice-agent/tree/main/frontend/components"
click node_frontend_api "https://github.com/ronincodex/voice-agent/blob/main/frontend/lib/api.ts"
click node_server "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/api/server.py"
click node_schemas "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/api/schemas.py"
click node_telephony "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/telephony/client.py"
click node_call_state "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/telephony/call_state.py"
click node_pipeline "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/pipeline/agent_pipeline.py"
click node_flow_nodes "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/pipeline/nodes.py"
click node_languages "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/config/languages.py"
click node_guardrail "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/pipeline/guardrail.py"
click node_validators "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/pipeline/validators.py"
click node_calling_window "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/compliance/calling_window.py"
click node_pii "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/compliance/pii.py"
click node_audit "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/db/audit.py"
click node_settings "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/config/settings.py"
click node_metrics "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/observability/metrics.py"
click node_supabase_store "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/db/supabase_client.py"
click node_agent_config "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/db/agent_config.py"
click node_redis_store "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/state/redis_store.py"
click node_recordings "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/storage/r2_client.py"
click node_summary "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/postcall/summarizer.py"
click node_fallback "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/observability/fallback.py"
click node_idempotency "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/observability/idempotency.py"
click node_retry "https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/observability/retry.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_dashboard_pages,node_dashboard_components,node_frontend_api,node_user toneBlue
class node_server,node_schemas,node_telephony,node_call_state,node_supabase,node_redis,node_r2 toneAmber
class node_pipeline,node_flow_nodes,node_languages toneMint
class node_supabase_store,node_agent_config,node_redis_store,node_recordings,node_summary,node_fallback toneRose
class node_guardrail,node_validators,node_calling_window,node_pii,node_audit,node_settings,node_metrics,node_idempotency,node_retry,node_phone,node_vobiz,node_sarvam,node_groq toneIndigo
```

## Components

### Dashboard

- [Dashboard pages](https://github.com/ronincodex/voice-agent/tree/main/frontend/app): `frontend/app`
- [Call views and forms](https://github.com/ronincodex/voice-agent/tree/main/frontend/components): `frontend/components`
- [API client](https://github.com/ronincodex/voice-agent/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### API and telephony

- [FastAPI server](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/api/server.py): `src/voice_agent/api/server.py`
- [API schemas](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/api/schemas.py): `src/voice_agent/api/schemas.py`
- [Vobiz adapter](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/telephony/client.py): `src/voice_agent/telephony/client.py`
- [Call tracking](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/telephony/call_state.py): `src/voice_agent/telephony/call_state.py`

### Conversation pipeline

- [Voice pipeline](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/pipeline/agent_pipeline.py): `src/voice_agent/pipeline/agent_pipeline.py`
- [Conversation stages](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/pipeline/nodes.py): `src/voice_agent/pipeline/nodes.py`
- [Language prompts](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/config/languages.py): `src/voice_agent/config/languages.py`

### Persistence and summaries

- [Call and transcript store](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/db/supabase_client.py): `src/voice_agent/db/supabase_client.py`
- [Agent configuration](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/db/agent_config.py): `src/voice_agent/db/agent_config.py`
- [Session state store](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/state/redis_store.py): `src/voice_agent/state/redis_store.py`
- [Recording storage](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/storage/r2_client.py): `src/voice_agent/storage/r2_client.py`
- [Post-call summary](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/postcall/summarizer.py): `src/voice_agent/postcall/summarizer.py`
- [Summary fallback](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/observability/fallback.py): `src/voice_agent/observability/fallback.py`

### Safety and operations

- [Input guardrail](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/pipeline/guardrail.py): `src/voice_agent/pipeline/guardrail.py`
- [Conversation validators](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/pipeline/validators.py): `src/voice_agent/pipeline/validators.py`
- [Calling window](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/compliance/calling_window.py): `src/voice_agent/compliance/calling_window.py`
- [PII masking](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/compliance/pii.py): `src/voice_agent/compliance/pii.py`
- [Compliance audit](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/db/audit.py): `src/voice_agent/db/audit.py`
- [App settings](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/config/settings.py): `src/voice_agent/config/settings.py`
- [Pipeline metrics](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/observability/metrics.py): `src/voice_agent/observability/metrics.py`
- [Idempotency](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/observability/idempotency.py): `src/voice_agent/observability/idempotency.py`
- [Retry policies](https://github.com/ronincodex/voice-agent/blob/main/src/voice_agent/observability/retry.py): `src/voice_agent/observability/retry.py`

### Other components

- **Dashboard user**
- **Phone caller**
- **Vobiz**
- **Sarvam AI**
- **Groq**
- **Supabase**
- **Upstash Redis**
- **Cloudflare R2**

## Connections

- Dashboard user → Dashboard pages: uses (evidence: `README.md`)
- Dashboard pages → Call views and forms: renders
- Dashboard pages → API client: requests data
- API client → FastAPI server: calls API (evidence: `README.md`)
- Phone caller → Vobiz: calls (evidence: `README.md`)
- Vobiz → FastAPI server: webhooks (evidence: `README.md`)
- FastAPI server → Vobiz adapter: initiates calls (evidence: `src/voice_agent/api/server.py`)
- FastAPI server → Call tracking: tracks calls (evidence: `src/voice_agent/api/server.py`)
- FastAPI server → Voice pipeline: starts conversation (evidence: `src/voice_agent/api/server.py`)
- FastAPI server → API schemas: validates API data (evidence: `src/voice_agent/api/server.py`)
- Voice pipeline → Conversation stages: initializes flow (evidence: `README.md`)
- Voice pipeline → Language prompts: loads language config (evidence: `src/voice_agent/pipeline/agent_pipeline.py`)
- Voice pipeline → Session state store: uses session state (evidence: `src/voice_agent/pipeline/agent_pipeline.py`)
- Voice pipeline → Call and transcript store: uses call data (evidence: `src/voice_agent/pipeline/agent_pipeline.py`)
- Voice pipeline → Compliance audit: records events (evidence: `src/voice_agent/pipeline/agent_pipeline.py`)
- Voice pipeline → Pipeline metrics: collects metrics (evidence: `src/voice_agent/pipeline/agent_pipeline.py`)
- Voice pipeline → Input guardrail: checks input (evidence: `src/voice_agent/pipeline/agent_pipeline.py`)
- Voice pipeline → Conversation validators: validates turns (evidence: `src/voice_agent/pipeline/agent_pipeline.py`)
- Voice pipeline → Sarvam AI: uses speech AI (evidence: `README.md`)
- FastAPI server → Calling window: enforces hours (evidence: `src/voice_agent/api/server.py`)
- FastAPI server → PII masking: masks transcripts (evidence: `src/voice_agent/api/server.py`)
- FastAPI server → Agent configuration: reads configuration (evidence: `src/voice_agent/api/server.py`)
- FastAPI server → Call and transcript store: reads and writes calls (evidence: `src/voice_agent/api/server.py`)
- FastAPI server → Recording storage: stores recordings (evidence: `src/voice_agent/api/server.py`)
- Recording storage → Cloudflare R2: uploads recordings (evidence: `README.md`)
- FastAPI server → Post-call summary: generates summary (evidence: `src/voice_agent/api/server.py`)
- Post-call summary → Groq: fallback summary (evidence: `src/voice_agent/postcall/summarizer.py`)
- Post-call summary → Sarvam AI: summarizes transcript (evidence: `src/voice_agent/postcall/summarizer.py`)
- Post-call summary → Summary fallback: uses fallback (evidence: `src/voice_agent/postcall/summarizer.py`)
- Call and transcript store → Supabase: persists records (evidence: `README.md`)
- Session state store → Upstash Redis: stores sessions (evidence: `README.md`)
- FastAPI server → App settings: loads configuration (evidence: `src/voice_agent/api/server.py`)
- Vobiz adapter → Retry policies: retries requests (evidence: `src/voice_agent/telephony/client.py`)
- Call and transcript store → Retry policies: retries database I/O (evidence: `src/voice_agent/db/supabase_client.py`)
- Recording storage → Retry policies: retries storage I/O (evidence: `src/voice_agent/storage/r2_client.py`)
- Conversation stages → Idempotency: uses idempotency (evidence: `src/voice_agent/pipeline/nodes.py`)
