# dummycodertech/voicekam architecture

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

- Interactive diagram: https://gitdiagram.com/dummycodertech/voicekam
- Repository: https://github.com/dummycodertech/voicekam

## Overview

Riya is a voice-first seller-retention assistant: a seller starts an inbound, proactive, or follow-up consultation in the browser; the service manages a phased session, grounds its conversation in deterministic seller diagnosis, captures commitments and a follow-up, and presents a recap. Supporting layers provide LLM streaming with provider failover and speech output. The README documents these capabilities; some frontend and backend wiring is unsampled, so those links are cited to the README rather than inferred from co-location.

Main entry points: [`app/main.py`](https://github.com/dummycodertech/voicekam/blob/main/app/main.py) (FastAPI Service), [`app/agent/orchestrator.py`](https://github.com/dummycodertech/voicekam/blob/main/app/agent/orchestrator.py) (Turn Orchestrator), [`app/llm/router.py`](https://github.com/dummycodertech/voicekam/blob/main/app/llm/router.py) (LLM Failover Router), [`frontend/app.js`](https://github.com/dummycodertech/voicekam/blob/main/frontend/app.js) (Call Interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Voice Experience"]
  node_web_ui["Call Interface<br/>[app.js]"]
  node_audio["Audio Playback<br/>[audio.js]"]
  node_brain["KAM Brain Panel<br/>[kam_brain.js]"]
  node_spectrum["Audio Visualizer<br/>[viz.js]"]
end

subgraph group_consultation["KAM Consultation"]
  node_api["FastAPI Service<br/>[main.py]"]
  node_settings["Runtime Settings<br/>[config.py]"]
  node_sessions[("Session State<br/>[session.py]")]
  node_phases["Call State Machine<br/>[state_machine.py]"]
  node_orchestrator["Turn Orchestrator<br/>[orchestrator.py]"]
  node_speech_text["Speakable Text<br/>[speakable.py]"]
end

subgraph group_intelligence["Grounded Intelligence"]
  node_tools["KAM Tool Dispatcher<br/>[tools.py]"]
  node_diagnosis["Seller Diagnosis<br/>[diagnosis.py]"]
  node_fixtures["Seller Fixtures<br/>[seed_data.py]"]
end

subgraph group_providers["AI Providers &amp; Speech"]
  node_llm_router["LLM Failover Router<br/>[router.py]"]
  node_llm_contract["Provider Interface<br/>[base.py]"]
  node_compat["OpenAI-Compatible Client<br/>[openai_compat.py]"]
  node_groq["Groq Adapter<br/>[groq_provider.py]"]
  node_gemini["Gemini Adapter<br/>[gemini_provider.py]"]
  node_openrouter["OpenRouter Adapter"]
  node_mock["Mock LLM<br/>[mock_provider.py]"]
  node_tts["Speech Synthesis<br/>[service.py]"]
end

node_seller(("Seller"))
node_browser(("Browser"))
node_llm_services{{"LLM Services"}}
node_speech_services{{"Speech Services"}}

node_seller -->|"uses"| node_web_ui
node_web_ui -->|"calls API"| node_api
node_api -->|"serves UI"| node_browser
node_web_ui -->|"queues audio"| node_audio
node_audio -->|"plays speech"| node_browser
node_web_ui -->|"updates panel"| node_brain
node_audio -->|"feeds audio"| node_spectrum
node_api -->|"loads"| node_settings
node_api -->|"creates and reads"| node_sessions
node_api -->|"streams turns"| node_orchestrator
node_api -->|"synthesizes speech"| node_tts
node_orchestrator -->|"updates"| node_sessions
node_orchestrator -->|"checks phase"| node_phases
node_orchestrator -->|"executes tools"| node_tools
node_orchestrator -->|"streams completion"| node_llm_router
node_orchestrator -->|"formats speech"| node_speech_text
node_tools -->|"dispatches analysis"| node_diagnosis
node_diagnosis -->|"reads data"| node_fixtures
node_tools -->|"records commitments"| node_sessions
node_sessions -->|"loads follow-up defaults"| node_fixtures
node_llm_router -->|"configures providers"| node_settings
node_llm_router -->|"selects provider"| node_groq
node_llm_router -->|"selects provider"| node_gemini
node_llm_router -->|"selects provider"| node_openrouter
node_llm_router -->|"selects provider"| node_mock
node_groq -->|"implements"| node_llm_contract
node_gemini -->|"implements"| node_llm_contract
node_mock -->|"implements"| node_llm_contract
node_groq -->|"uses client"| node_compat
node_openrouter -->|"uses client"| node_compat
node_compat -->|"calls API"| node_llm_services
node_gemini -->|"calls API"| node_llm_services
node_tts -->|"tries speech providers"| node_speech_services
node_tts -->|"signals browser fallback"| node_browser

click node_web_ui "https://github.com/dummycodertech/voicekam/blob/main/frontend/app.js"
click node_audio "https://github.com/dummycodertech/voicekam/blob/main/frontend/audio.js"
click node_brain "https://github.com/dummycodertech/voicekam/blob/main/frontend/kam_brain.js"
click node_spectrum "https://github.com/dummycodertech/voicekam/blob/main/frontend/viz.js"
click node_api "https://github.com/dummycodertech/voicekam/blob/main/app/main.py"
click node_settings "https://github.com/dummycodertech/voicekam/blob/main/app/config.py"
click node_sessions "https://github.com/dummycodertech/voicekam/blob/main/app/agent/session.py"
click node_phases "https://github.com/dummycodertech/voicekam/blob/main/app/agent/state_machine.py"
click node_orchestrator "https://github.com/dummycodertech/voicekam/blob/main/app/agent/orchestrator.py"
click node_speech_text "https://github.com/dummycodertech/voicekam/blob/main/app/agent/speakable.py"
click node_tools "https://github.com/dummycodertech/voicekam/blob/main/app/engine/tools.py"
click node_diagnosis "https://github.com/dummycodertech/voicekam/blob/main/app/engine/diagnosis.py"
click node_fixtures "https://github.com/dummycodertech/voicekam/blob/main/app/data/seed_data.py"
click node_llm_router "https://github.com/dummycodertech/voicekam/blob/main/app/llm/router.py"
click node_llm_contract "https://github.com/dummycodertech/voicekam/blob/main/app/llm/base.py"
click node_compat "https://github.com/dummycodertech/voicekam/blob/main/app/llm/openai_compat.py"
click node_groq "https://github.com/dummycodertech/voicekam/blob/main/app/llm/groq_provider.py"
click node_gemini "https://github.com/dummycodertech/voicekam/blob/main/app/llm/gemini_provider.py"
click node_openrouter "https://github.com/dummycodertech/voicekam/blob/main/app/llm/openrouter_provider.py"
click node_mock "https://github.com/dummycodertech/voicekam/blob/main/app/llm/mock_provider.py"
click node_tts "https://github.com/dummycodertech/voicekam/blob/main/app/tts/service.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_web_ui,node_audio,node_brain,node_spectrum,node_browser toneBlue
class node_api,node_settings,node_sessions,node_phases,node_orchestrator,node_speech_text toneAmber
class node_tools,node_diagnosis,node_fixtures toneMint
class node_llm_router,node_llm_contract,node_compat,node_groq,node_gemini,node_openrouter,node_mock,node_tts toneRose
class node_seller,node_llm_services,node_speech_services toneIndigo
```

## Components

### Voice Experience

- [Call Interface](https://github.com/dummycodertech/voicekam/blob/main/frontend/app.js): `frontend/app.js`
- [Audio Playback](https://github.com/dummycodertech/voicekam/blob/main/frontend/audio.js): `frontend/audio.js`
- [KAM Brain Panel](https://github.com/dummycodertech/voicekam/blob/main/frontend/kam_brain.js): `frontend/kam_brain.js`
- [Audio Visualizer](https://github.com/dummycodertech/voicekam/blob/main/frontend/viz.js): `frontend/viz.js`

### KAM Consultation

- [FastAPI Service](https://github.com/dummycodertech/voicekam/blob/main/app/main.py): `app/main.py`
- [Runtime Settings](https://github.com/dummycodertech/voicekam/blob/main/app/config.py): `app/config.py`
- [Session State](https://github.com/dummycodertech/voicekam/blob/main/app/agent/session.py): `app/agent/session.py`
- [Call State Machine](https://github.com/dummycodertech/voicekam/blob/main/app/agent/state_machine.py): `app/agent/state_machine.py`
- [Turn Orchestrator](https://github.com/dummycodertech/voicekam/blob/main/app/agent/orchestrator.py): `app/agent/orchestrator.py`
- [Speakable Text](https://github.com/dummycodertech/voicekam/blob/main/app/agent/speakable.py): `app/agent/speakable.py`

### Grounded Intelligence

- [KAM Tool Dispatcher](https://github.com/dummycodertech/voicekam/blob/main/app/engine/tools.py): `app/engine/tools.py`
- [Seller Diagnosis](https://github.com/dummycodertech/voicekam/blob/main/app/engine/diagnosis.py): `app/engine/diagnosis.py`
- [Seller Fixtures](https://github.com/dummycodertech/voicekam/blob/main/app/data/seed_data.py): `app/data/seed_data.py`

### AI Providers & Speech

- [LLM Failover Router](https://github.com/dummycodertech/voicekam/blob/main/app/llm/router.py): `app/llm/router.py`
- [Provider Interface](https://github.com/dummycodertech/voicekam/blob/main/app/llm/base.py): `app/llm/base.py`
- [OpenAI-Compatible Client](https://github.com/dummycodertech/voicekam/blob/main/app/llm/openai_compat.py): `app/llm/openai_compat.py`
- [Groq Adapter](https://github.com/dummycodertech/voicekam/blob/main/app/llm/groq_provider.py): `app/llm/groq_provider.py`
- [Gemini Adapter](https://github.com/dummycodertech/voicekam/blob/main/app/llm/gemini_provider.py): `app/llm/gemini_provider.py`
- [OpenRouter Adapter](https://github.com/dummycodertech/voicekam/blob/main/app/llm/openrouter_provider.py): `app/llm/openrouter_provider.py`
- [Mock LLM](https://github.com/dummycodertech/voicekam/blob/main/app/llm/mock_provider.py): `app/llm/mock_provider.py`
- [Speech Synthesis](https://github.com/dummycodertech/voicekam/blob/main/app/tts/service.py): `app/tts/service.py`

### Other components

- **Seller**
- **Browser**
- **LLM Services**
- **Speech Services**

## Connections

- Seller → Call Interface: uses (evidence: `README.md`)
- Call Interface → FastAPI Service: calls API (evidence: `README.md`)
- FastAPI Service → Browser: serves UI (evidence: `README.md`)
- Call Interface → Audio Playback: queues audio (evidence: `README.md`)
- Audio Playback → Browser: plays speech (evidence: `README.md`)
- Call Interface → KAM Brain Panel: updates panel (evidence: `README.md`)
- Audio Playback → Audio Visualizer: feeds audio (evidence: `README.md`)
- FastAPI Service → Runtime Settings: loads (evidence: `app/main.py`)
- FastAPI Service → Session State: creates and reads (evidence: `app/main.py`)
- FastAPI Service → Turn Orchestrator: streams turns (evidence: `app/main.py`)
- FastAPI Service → Speech Synthesis: synthesizes speech (evidence: `README.md`)
- Turn Orchestrator → Session State: updates (evidence: `app/agent/orchestrator.py`)
- Turn Orchestrator → Call State Machine: checks phase (evidence: `app/agent/orchestrator.py`)
- Turn Orchestrator → KAM Tool Dispatcher: executes tools (evidence: `app/agent/orchestrator.py`)
- Turn Orchestrator → LLM Failover Router: streams completion (evidence: `app/agent/orchestrator.py`)
- Turn Orchestrator → Speakable Text: formats speech (evidence: `app/agent/orchestrator.py`)
- KAM Tool Dispatcher → Seller Diagnosis: dispatches analysis (evidence: `app/engine/tools.py`)
- Seller Diagnosis → Seller Fixtures: reads data (evidence: `app/engine/diagnosis.py`)
- KAM Tool Dispatcher → Session State: records commitments (evidence: `app/engine/tools.py`)
- Session State → Seller Fixtures: loads follow-up defaults (evidence: `app/agent/session.py`)
- LLM Failover Router → Runtime Settings: configures providers (evidence: `app/llm/router.py`)
- LLM Failover Router → Groq Adapter: selects provider (evidence: `app/llm/router.py`)
- LLM Failover Router → Gemini Adapter: selects provider (evidence: `app/llm/router.py`)
- LLM Failover Router → OpenRouter Adapter: selects provider (evidence: `app/llm/router.py`)
- LLM Failover Router → Mock LLM: selects provider (evidence: `app/llm/router.py`)
- Groq Adapter → Provider Interface: implements (evidence: `app/llm/groq_provider.py`)
- Gemini Adapter → Provider Interface: implements (evidence: `app/llm/gemini_provider.py`)
- Mock LLM → Provider Interface: implements (evidence: `app/llm/mock_provider.py`)
- Groq Adapter → OpenAI-Compatible Client: uses client (evidence: `app/llm/groq_provider.py`)
- OpenRouter Adapter → OpenAI-Compatible Client: uses client (evidence: `app/llm/openrouter_provider.py`)
- OpenAI-Compatible Client → LLM Services: calls API (evidence: `README.md`)
- Gemini Adapter → LLM Services: calls API (evidence: `README.md`)
- Speech Synthesis → Speech Services: tries speech providers (evidence: `README.md`)
- Speech Synthesis → Browser: signals browser fallback (evidence: `README.md`)