# ujjwalagrawal3950/voice-assistance- architecture

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

- Interactive diagram: https://gitdiagram.com/ujjwalagrawal3950/voice-assistance-
- Repository: https://github.com/ujjwalagrawal3950/voice-assistance-

## Overview

Virtual KAM is a seller-facing commerce intelligence and AI account-management application. Sellers use the React workspace for dashboards, product and recommendation views, and text or voice conversations; the backend supplies deterministic business analysis and specialist-guided answers, while recommendations can be reviewed and acted on. Voice runs through a separate WebSocket service for transcription and speech synthesis, with recommendation actions relayed to the backend. The README documents the major capabilities; several API and domain modules were not sampled, so their internal call relationships are not inferred.

Main entry points: [`backend/app/agent/service.py`](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/agent/service.py) (Agent Coordinator), [`backend/app/api`](https://github.com/ujjwalagrawal3950/voice-assistance-/tree/main/backend/app/api) (REST API), [`voice-service/main.py`](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/voice-service/main.py) (Voice WebSocket), [`frontend/src/api/client.ts`](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/frontend/src/api/client.ts) (REST Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Seller Workspace"]
  node_app["Workspace Routes<br/>[App.tsx]"]
  node_chat_ui["Chat Workspace<br/>[KAMWorkspace.tsx]"]
  node_voice_hook["Voice Controls<br/>[useVoice.ts]"]
  node_dash["Analytics Dashboard<br/>[Dashboard.tsx]"]
  node_recommend_ui["Recommendations UI"]
  node_api_client["REST Client<br/>[client.ts]"]
end

subgraph group_backend["Commerce Backend"]
  node_api_routes["REST API"]
  node_commerce["Commerce Analytics<br/>[intelligence.py]"]
  node_kpis["KPI Analytics<br/>[kpi.py]"]
  node_forecast["Forecasting<br/>[forecasting.py]"]
  node_recommendations["Recommendations<br/>[recommendations.py]"]
  node_persistence[("Commerce Database<br/>[database.py]")]
end

subgraph group_agent["KAM Agent"]
  node_agent_service["Agent Coordinator<br/>[service.py]"]
  node_guardrails["Input Guardrails<br/>[guardrails.py]"]
  node_specialists["Domain Specialists<br/>[specialists.py]"]
  node_agent_tools["Business Tools<br/>[tools.py]"]
  node_context["Context Manager<br/>[context_manager.py]"]
  node_memory_store[("Conversation Memory<br/>[store.py]")]
  node_extractor["Memory Extractor<br/>[extractor.py]"]
end

subgraph group_voice["Voice Interface"]
  node_voice_service["Voice WebSocket<br/>[main.py]"]
  node_voice_engines["Speech Engines<br/>[voice_engines.py]"]
end

node_seller(("Seller"))
node_gemini["Gemini API"]
node_whisper["Whisper STT"]
node_tts["Edge / Piper TTS"]

node_seller -->|"uses"| node_app
node_app -->|"routes to"| node_chat_ui
node_app -->|"routes to"| node_dash
node_app -->|"routes to"| node_recommend_ui
node_chat_ui -->|"sends chat"| node_api_client
node_voice_hook -->|"opens WebSocket"| node_voice_service
node_voice_hook -->|"sends text chat"| node_api_client
node_dash -.->|"fetches analytics"| node_api_client
node_recommend_ui -.->|"manages actions"| node_api_client
node_api_client -->|"HTTP requests"| node_api_routes
node_api_routes -.->|"serves analysis"| node_commerce
node_api_routes -.->|"serves forecasts"| node_forecast
node_api_routes -.->|"serves decisions"| node_recommendations
node_commerce -.->|"queries records"| node_persistence
node_kpis -.->|"queries records"| node_persistence
node_forecast -.->|"uses seller data"| node_persistence
node_recommendations -.->|"stores decisions"| node_persistence
node_api_routes -.->|"dispatches chat"| node_agent_service
node_agent_service -->|"checks requests"| node_guardrails
node_agent_service -->|"builds briefs"| node_specialists
node_agent_service -->|"runs tools"| node_agent_tools
node_agent_service -->|"assembles context"| node_context
node_agent_service -->|"requests reasoning"| node_gemini
node_context -->|"retrieves and stores"| node_memory_store
node_context -->|"extracts facts"| node_extractor
node_voice_service -->|"posts chat"| node_api_routes
node_voice_service -->|"reads and updates"| node_recommendations
node_voice_service -->|"synthesizes speech"| node_voice_engines
node_voice_service -->|"transcribes audio"| node_whisper
node_voice_engines -->|"generates audio"| node_tts

click node_app "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/frontend/src/App.tsx"
click node_chat_ui "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/frontend/src/components/kam/KAMWorkspace.tsx"
click node_voice_hook "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/frontend/src/hooks/useVoice.ts"
click node_dash "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/frontend/src/components/dashboard/Dashboard.tsx"
click node_recommend_ui "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/frontend/src/components/recommendations/RecommendationList.tsx"
click node_api_client "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/frontend/src/api/client.ts"
click node_api_routes "https://github.com/ujjwalagrawal3950/voice-assistance-/tree/main/backend/app/api"
click node_commerce "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/services/intelligence.py"
click node_kpis "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/services/kpi.py"
click node_forecast "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/services/forecasting.py"
click node_recommendations "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/api/recommendations.py"
click node_persistence "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/database.py"
click node_agent_service "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/agent/service.py"
click node_guardrails "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/agent/guardrails.py"
click node_specialists "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/agent/specialists.py"
click node_agent_tools "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/agent/tools.py"
click node_context "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/memory/context_manager.py"
click node_memory_store "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/memory/store.py"
click node_extractor "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/memory/extractor.py"
click node_voice_service "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/voice-service/main.py"
click node_voice_engines "https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/voice-service/voice_engines.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_chat_ui,node_voice_hook,node_dash,node_recommend_ui,node_api_client toneBlue
class node_api_routes,node_commerce,node_kpis,node_forecast,node_recommendations,node_persistence toneAmber
class node_agent_service,node_guardrails,node_specialists,node_agent_tools,node_context,node_memory_store,node_extractor,node_gemini toneMint
class node_voice_service,node_voice_engines toneRose
class node_seller,node_whisper,node_tts toneIndigo
```

## Components

### Seller Workspace

- [Workspace Routes](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Chat Workspace](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/frontend/src/components/kam/KAMWorkspace.tsx): `frontend/src/components/kam/KAMWorkspace.tsx`
- [Voice Controls](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/frontend/src/hooks/useVoice.ts): `frontend/src/hooks/useVoice.ts`
- [Analytics Dashboard](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/frontend/src/components/dashboard/Dashboard.tsx): `frontend/src/components/dashboard/Dashboard.tsx`
- [Recommendations UI](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/frontend/src/components/recommendations/RecommendationList.tsx): `frontend/src/components/recommendations/RecommendationList.tsx`
- [REST Client](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Commerce Backend

- [REST API](https://github.com/ujjwalagrawal3950/voice-assistance-/tree/main/backend/app/api): `backend/app/api`
- [Commerce Analytics](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/services/intelligence.py): `backend/app/services/intelligence.py`
- [KPI Analytics](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/services/kpi.py): `backend/app/services/kpi.py`
- [Forecasting](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/services/forecasting.py): `backend/app/services/forecasting.py`
- [Recommendations](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/api/recommendations.py): `backend/app/api/recommendations.py`
- [Commerce Database](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/database.py): `backend/app/database.py`

### KAM Agent

- [Agent Coordinator](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/agent/service.py): `backend/app/agent/service.py`
- [Input Guardrails](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/agent/guardrails.py): `backend/app/agent/guardrails.py`
- [Domain Specialists](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/agent/specialists.py): `backend/app/agent/specialists.py`
- [Business Tools](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/agent/tools.py): `backend/app/agent/tools.py`
- [Context Manager](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/memory/context_manager.py): `backend/app/memory/context_manager.py`
- [Conversation Memory](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/memory/store.py): `backend/app/memory/store.py`
- [Memory Extractor](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/backend/app/memory/extractor.py): `backend/app/memory/extractor.py`

### Voice Interface

- [Voice WebSocket](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/voice-service/main.py): `voice-service/main.py`
- [Speech Engines](https://github.com/ujjwalagrawal3950/voice-assistance-/blob/main/voice-service/voice_engines.py): `voice-service/voice_engines.py`

### Other components

- **Seller**
- **Gemini API**
- **Whisper STT**
- **Edge / Piper TTS**

## Connections

- Seller → Workspace Routes: uses (evidence: `README.md`)
- Workspace Routes → Chat Workspace: routes to (evidence: `frontend/src/App.tsx`)
- Workspace Routes → Analytics Dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Workspace Routes → Recommendations UI: routes to (evidence: `frontend/src/App.tsx`)
- Chat Workspace → REST Client: sends chat
- Voice Controls → Voice WebSocket: opens WebSocket (evidence: `README.md`)
- Voice Controls → REST Client: sends text chat (evidence: `frontend/src/hooks/useVoice.ts`)
- Analytics Dashboard → REST Client: fetches analytics
- Recommendations UI → REST Client: manages actions
- REST Client → REST API: HTTP requests (evidence: `frontend/src/api/client.ts`)
- REST API → Commerce Analytics: serves analysis
- REST API → Forecasting: serves forecasts
- REST API → Recommendations: serves decisions
- Commerce Analytics → Commerce Database: queries records
- KPI Analytics → Commerce Database: queries records
- Forecasting → Commerce Database: uses seller data
- Recommendations → Commerce Database: stores decisions
- REST API → Agent Coordinator: dispatches chat
- Agent Coordinator → Input Guardrails: checks requests (evidence: `backend/app/agent/service.py`)
- Agent Coordinator → Domain Specialists: builds briefs (evidence: `backend/app/agent/service.py`)
- Agent Coordinator → Business Tools: runs tools (evidence: `backend/app/agent/service.py`)
- Agent Coordinator → Context Manager: assembles context (evidence: `backend/app/agent/service.py`)
- Agent Coordinator → Gemini API: requests reasoning (evidence: `README.md`)
- Context Manager → Conversation Memory: retrieves and stores (evidence: `backend/app/memory/context_manager.py`)
- Context Manager → Memory Extractor: extracts facts (evidence: `backend/app/memory/context_manager.py`)
- Voice WebSocket → REST API: posts chat (evidence: `voice-service/main.py`)
- Voice WebSocket → Recommendations: reads and updates
- Voice WebSocket → Speech Engines: synthesizes speech (evidence: `voice-service/main.py`)
- Voice WebSocket → Whisper STT: transcribes audio (evidence: `README.md`)
- Speech Engines → Edge / Piper TTS: generates audio (evidence: `voice-service/voice_engines.py`)