# piiyush-joshii/voice-bot-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/piiyush-joshii/voice-bot-v2
- Repository: https://github.com/piiyush-joshii/voice-bot-v2

## Overview

This repository is a local voice-and-text electronic bill presentment and payment (EBPP) proof of concept. A web caller starts a session; the voice agent handles text or audio turns, authenticates the account, answers bill/history questions, and can initiate payment or hand off to a human. Card entry is isolated in a separate payment service, with payment outcomes returned to the conversation. The graph follows documented capabilities and shown call paths; links to unsampled subsystem internals are kept at service level.

Main entry points: [`services/voice-agent/app/pipeline.py`](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/pipeline.py) (Audio Pipeline), [`services/voice-agent/app/brain/conversation.py`](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/brain/conversation.py) (Turn Orchestrator), [`services/voice-agent/app/api/routes.py`](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/api/routes.py) (Voice API), [`web/src/App.tsx`](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/web/src/App.tsx) (Console App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Console"]
  node_app["Console App<br/>[App.tsx]"]
  node_webapi["Backend Client<br/>[backend.ts]"]
  node_websession["Session Client<br/>[sessions.ts]"]
  node_webrtc["Voice WebRTC<br/>[webrtc.ts]"]
end

subgraph group_voice["Voice Agent"]
  node_voiceapi["Voice API<br/>[routes.py]"]
  node_sessions["Session Registry<br/>[sessions.py]"]
  node_pipeline["Audio Pipeline<br/>[pipeline.py]"]
  node_speech["ASR and TTS<br/>[speech.py]"]
  node_scrubber["Transcript Scrubber<br/>[scrubber.py]"]
  node_metrics["Pipeline Metrics<br/>[metrics.py]"]
  node_gate["Payment Gate<br/>[state.py]"]
end

subgraph group_brain["Conversation Brain"]
  node_conversation["Turn Orchestrator<br/>[conversation.py]"]
  node_router["Intent and FAQ Router<br/>[router.py]"]
  node_llm["LLM Service<br/>[llm.py]"]
  node_tools["Conversation Tools<br/>[tools.py]"]
  node_clients["Service Clients<br/>[clients.py]"]
end

subgraph group_billing["Billing API"]
  node_backend["Billing Routes<br/>[bills.py]"]
  node_auth["Authentication Routes<br/>[auth.py]"]
  node_backendpayments["Payment Records<br/>[payments.py]"]
  node_mockdata[("Mock Account Store<br/>[mock_data.py]")]
  node_notification["Notifications<br/>[notifications.py]"]
end

subgraph group_payments["PCI Payment"]
  node_capture["PCI Capture Service<br/>[main.py]"]
  node_captureui["Secure Capture UI<br/>[capture.js]"]
  node_webhook["Payment Webhook<br/>[webhook.py]"]
end

node_caller(("Caller"))

node_caller -->|"uses"| node_app
node_app -->|"fetches bills"| node_webapi
node_app -->|"creates sessions"| node_websession
node_app -->|"starts voice"| node_webrtc
node_websession -.->|"HTTP sessions"| node_voiceapi
node_webrtc -.->|"WebRTC"| node_voiceapi
node_webapi -.->|"requests bills"| node_backend
node_voiceapi -->|"looks up sessions"| node_sessions
node_voiceapi -->|"handles turns"| node_conversation
node_voiceapi -->|"builds voice task"| node_pipeline
node_pipeline -->|"builds ASR and TTS"| node_speech
node_pipeline -->|"scrubs transcripts"| node_scrubber
node_pipeline -->|"gates capture"| node_gate
node_pipeline -->|"taps pipeline"| node_metrics
node_pipeline -->|"runs turns"| node_conversation
node_conversation -->|"routes intent"| node_router
node_conversation -->|"requests decisions"| node_llm
node_conversation -->|"executes tools"| node_tools
node_conversation -->|"checks gate state"| node_gate
node_tools -.->|"uses service clients"| node_clients
node_clients -->|"calls billing API"| node_backend
node_clients -->|"creates payment session"| node_capture
node_backend -->|"reads bill data"| node_mockdata
node_auth -->|"checks account"| node_mockdata
node_backendpayments -->|"records payment"| node_mockdata
node_capture -.->|"serves capture UI"| node_captureui
node_capture -->|"sends event"| node_webhook
node_webhook -.->|"posts payment event"| node_voiceapi
node_tools -.->|"sends receipt notice"| node_notification

click node_app "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/web/src/App.tsx"
click node_webapi "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/web/src/api/backend.ts"
click node_websession "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/web/src/api/sessions.ts"
click node_webrtc "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/web/src/voice/webrtc.ts"
click node_voiceapi "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/api/routes.py"
click node_sessions "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/sessions.py"
click node_pipeline "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/pipeline.py"
click node_speech "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/services/speech.py"
click node_scrubber "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/processors/scrubber.py"
click node_metrics "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/processors/metrics.py"
click node_gate "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/gate/state.py"
click node_conversation "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/brain/conversation.py"
click node_router "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/processors/router.py"
click node_llm "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/services/llm.py"
click node_tools "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/brain/tools.py"
click node_clients "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/clients.py"
click node_backend "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/backend-api/app/routes/bills.py"
click node_auth "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/backend-api/app/routes/auth.py"
click node_backendpayments "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/backend-api/app/routes/payments.py"
click node_mockdata "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/backend-api/app/mock_data.py"
click node_notification "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/backend-api/app/routes/notifications.py"
click node_capture "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/payment-service/app/main.py"
click node_captureui "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/payment-service/app/static/capture.js"
click node_webhook "https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/payment-service/app/webhook.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_app,node_webapi,node_websession,node_webrtc toneBlue
class node_voiceapi,node_sessions,node_pipeline,node_speech,node_scrubber,node_metrics,node_gate toneAmber
class node_conversation,node_router,node_llm,node_tools,node_clients toneMint
class node_backend,node_auth,node_backendpayments,node_mockdata,node_notification toneRose
class node_capture,node_captureui,node_webhook,node_caller toneIndigo
```

## Components

### Web Console

- [Console App](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Backend Client](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/web/src/api/backend.ts): `web/src/api/backend.ts`
- [Session Client](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/web/src/api/sessions.ts): `web/src/api/sessions.ts`
- [Voice WebRTC](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/web/src/voice/webrtc.ts): `web/src/voice/webrtc.ts`

### Voice Agent

- [Voice API](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/api/routes.py): `services/voice-agent/app/api/routes.py`
- [Session Registry](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/sessions.py): `services/voice-agent/app/sessions.py`
- [Audio Pipeline](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/pipeline.py): `services/voice-agent/app/pipeline.py`
- [ASR and TTS](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/services/speech.py): `services/voice-agent/app/services/speech.py`
- [Transcript Scrubber](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/processors/scrubber.py): `services/voice-agent/app/processors/scrubber.py`
- [Pipeline Metrics](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/processors/metrics.py): `services/voice-agent/app/processors/metrics.py`
- [Payment Gate](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/gate/state.py): `services/voice-agent/app/gate/state.py`

### Conversation Brain

- [Turn Orchestrator](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/brain/conversation.py): `services/voice-agent/app/brain/conversation.py`
- [Intent and FAQ Router](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/processors/router.py): `services/voice-agent/app/processors/router.py`
- [LLM Service](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/services/llm.py): `services/voice-agent/app/services/llm.py`
- [Conversation Tools](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/brain/tools.py): `services/voice-agent/app/brain/tools.py`
- [Service Clients](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/voice-agent/app/clients.py): `services/voice-agent/app/clients.py`

### Billing API

- [Billing Routes](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/backend-api/app/routes/bills.py): `services/backend-api/app/routes/bills.py`
- [Authentication Routes](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/backend-api/app/routes/auth.py): `services/backend-api/app/routes/auth.py`
- [Payment Records](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/backend-api/app/routes/payments.py): `services/backend-api/app/routes/payments.py`
- [Mock Account Store](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/backend-api/app/mock_data.py): `services/backend-api/app/mock_data.py`
- [Notifications](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/backend-api/app/routes/notifications.py): `services/backend-api/app/routes/notifications.py`

### PCI Payment

- [PCI Capture Service](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/payment-service/app/main.py): `services/payment-service/app/main.py`
- [Secure Capture UI](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/payment-service/app/static/capture.js): `services/payment-service/app/static/capture.js`
- [Payment Webhook](https://github.com/piiyush-joshii/voice-bot-v2/blob/main/services/payment-service/app/webhook.py): `services/payment-service/app/webhook.py`

### Other components

- **Caller**

## Connections

- Caller → Console App: uses (evidence: `README.md`)
- Console App → Backend Client: fetches bills (evidence: `web/src/App.tsx`)
- Console App → Session Client: creates sessions (evidence: `web/src/App.tsx`)
- Console App → Voice WebRTC: starts voice (evidence: `web/src/App.tsx`)
- Session Client → Voice API: HTTP sessions
- Voice WebRTC → Voice API: WebRTC
- Backend Client → Billing Routes: requests bills
- Voice API → Session Registry: looks up sessions (evidence: `services/voice-agent/app/api/routes.py`)
- Voice API → Turn Orchestrator: handles turns (evidence: `services/voice-agent/app/api/routes.py`)
- Voice API → Audio Pipeline: builds voice task (evidence: `services/voice-agent/app/api/routes.py`)
- Audio Pipeline → ASR and TTS: builds ASR and TTS (evidence: `services/voice-agent/app/pipeline.py`)
- Audio Pipeline → Transcript Scrubber: scrubs transcripts (evidence: `services/voice-agent/app/pipeline.py`)
- Audio Pipeline → Payment Gate: gates capture (evidence: `services/voice-agent/app/pipeline.py`)
- Audio Pipeline → Pipeline Metrics: taps pipeline (evidence: `services/voice-agent/app/pipeline.py`)
- Audio Pipeline → Turn Orchestrator: runs turns (evidence: `services/voice-agent/app/pipeline.py`)
- Turn Orchestrator → Intent and FAQ Router: routes intent (evidence: `services/voice-agent/app/brain/conversation.py`)
- Turn Orchestrator → LLM Service: requests decisions (evidence: `services/voice-agent/app/brain/conversation.py`)
- Turn Orchestrator → Conversation Tools: executes tools (evidence: `services/voice-agent/app/brain/conversation.py`)
- Turn Orchestrator → Payment Gate: checks gate state (evidence: `services/voice-agent/app/brain/conversation.py`)
- Conversation Tools → Service Clients: uses service clients
- Service Clients → Billing Routes: calls billing API (evidence: `services/voice-agent/app/clients.py`)
- Service Clients → PCI Capture Service: creates payment session (evidence: `services/voice-agent/app/clients.py`)
- Billing Routes → Mock Account Store: reads bill data (evidence: `services/backend-api/app/routes/bills.py`)
- Authentication Routes → Mock Account Store: checks account (evidence: `services/backend-api/app/routes/auth.py`)
- Payment Records → Mock Account Store: records payment (evidence: `services/backend-api/app/routes/payments.py`)
- PCI Capture Service → Secure Capture UI: serves capture UI
- PCI Capture Service → Payment Webhook: sends event (evidence: `services/payment-service/app/main.py`)
- Payment Webhook → Voice API: posts payment event
- Conversation Tools → Notifications: sends receipt notice
