# prachig-microsoft/customer-chatbot-solution-accelerator architecture

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

- Interactive diagram: https://gitdiagram.com/prachig-microsoft/customer-chatbot-solution-accelerator
- Repository: https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator

## Overview

This repository is an Azure customer-support chatbot accelerator, pairing an ecommerce, healthcare, or banking scenario host with an embeddable text-and-voice chat service. Customers browse scenario content or ask questions; the chat service routes requests through Foundry agents, which use scenario-specific catalog and policy knowledge to respond. The host also exposes scenario APIs and persists business and conversation data. The README documents the overall product capabilities; sampled source confirms API registration, scenario configuration, authentication, and Cosmos-backed data access, while some domain and agent internals were not sampled.

Main entry points: [`chat-app/backend/app/routers/chat.py`](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/routers/chat.py) (Chat Handler), [`chat-app/backend/app/routers/voice_live.py`](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/routers/voice_live.py) (Voice Live), [`scenario-app/frontend/src/scenarios/ScenarioApp.tsx`](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/scenario-app/frontend/src/scenarios/ScenarioApp.tsx) (Scenario UI), [`scenario-app/backend/app/main.py`](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/scenario-app/backend/app/main.py) (Scenario API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Scenario Host"]
  node_scenario_ui["Scenario UI<br/>[ScenarioApp.tsx]"]
  node_scenario_api["Scenario API<br/>[main.py]"]
  node_domain_routes["Domain APIs"]
  node_scenario_embed["Widget Embed<br/>[embedChatWidget.ts]"]
end

subgraph group_widget["Chat Experience"]
  node_chat_ui["Chat Widget UI"]
end

subgraph group_services["Chat Services"]
  node_chat_api["Chat API<br/>[main.py]"]
  node_chat_routes["Chat Handler<br/>[chat.py]"]
  node_voice_routes["Voice Live<br/>[voice_live.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_scenario_settings["Scenario Config<br/>[scenario_config.py]"]
  node_agent_orchestration["Agent Orchestration"]
end

subgraph group_data["Knowledge and Data"]
  node_foundry{{"Azure AI Foundry"}}
  node_search["Hybrid Search<br/>[search.py]"]
  node_cosmos[("Cosmos Data<br/>[cosmos_service.py]")]
  node_database_factory["Database Service<br/>[database.py]"]
  node_scenario_cosmos[("Host Data Store<br/>[cosmos_service.py]")]
  node_scenario_search["Scenario Search<br/>[search.py]"]
end

node_customer(("Customer"))

node_customer -->|"browses"| node_scenario_ui
node_customer -->|"asks questions"| node_chat_ui
node_scenario_ui -.->|"requests data"| node_scenario_api
node_scenario_ui -->|"embeds"| node_scenario_embed
node_scenario_embed -->|"loads widget"| node_chat_ui
node_chat_ui -->|"sends messages"| node_chat_api
node_chat_api -->|"registers routes"| node_chat_routes
node_chat_api -->|"registers routes"| node_voice_routes
node_scenario_api -->|"registers routes"| node_domain_routes
node_chat_routes -->|"checks identity"| node_auth
node_voice_routes -->|"checks identity"| node_auth
node_chat_routes -->|"reads scenario"| node_scenario_settings
node_voice_routes -->|"reads scenario"| node_scenario_settings
node_chat_routes -.->|"invokes agents"| node_agent_orchestration
node_voice_routes -->|"uses grounding"| node_agent_orchestration
node_agent_orchestration -->|"routes queries"| node_foundry
node_foundry -->|"retrieves knowledge"| node_search
node_search -.->|"returns matches"| node_foundry
node_chat_routes -->|"uses persistence"| node_database_factory
node_database_factory -->|"selects implementation"| node_cosmos
node_domain_routes -.->|"uses data store"| node_scenario_cosmos
node_domain_routes -.->|"uses search"| node_scenario_search
node_scenario_api -->|"selects scenario"| node_scenario_settings

click node_scenario_ui "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/scenario-app/frontend/src/scenarios/ScenarioApp.tsx"
click node_scenario_api "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/scenario-app/backend/app/main.py"
click node_domain_routes "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/tree/main/scenario-app/backend/app/routers"
click node_scenario_embed "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/scenario-app/frontend/src/embedChatWidget.ts"
click node_chat_ui "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/frontend/src/components/EnhancedChatPanel.tsx"
click node_chat_api "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/main.py"
click node_chat_routes "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/routers/chat.py"
click node_voice_routes "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/routers/voice_live.py"
click node_auth "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/auth.py"
click node_scenario_settings "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/scenario_config.py"
click node_agent_orchestration "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/utils/foundry_agent_utils.py"
click node_search "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/services/search.py"
click node_cosmos "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/cosmos_service.py"
click node_database_factory "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/database.py"
click node_scenario_cosmos "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/scenario-app/backend/app/cosmos_service.py"
click node_scenario_search "https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/scenario-app/backend/app/services/search.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_scenario_ui,node_scenario_api,node_domain_routes,node_scenario_embed toneBlue
class node_chat_ui toneAmber
class node_chat_api,node_chat_routes,node_voice_routes,node_auth,node_scenario_settings,node_agent_orchestration toneMint
class node_foundry,node_search,node_cosmos,node_database_factory,node_scenario_cosmos,node_scenario_search toneRose
class node_customer toneIndigo
```

## Components

### Scenario Host

- [Scenario UI](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/scenario-app/frontend/src/scenarios/ScenarioApp.tsx): `scenario-app/frontend/src/scenarios/ScenarioApp.tsx`
- [Scenario API](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/scenario-app/backend/app/main.py): `scenario-app/backend/app/main.py`
- [Domain APIs](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/tree/main/scenario-app/backend/app/routers): `scenario-app/backend/app/routers`
- [Widget Embed](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/scenario-app/frontend/src/embedChatWidget.ts): `scenario-app/frontend/src/embedChatWidget.ts`

### Chat Experience

- [Chat Widget UI](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/frontend/src/components/EnhancedChatPanel.tsx): `chat-app/frontend/src/components/EnhancedChatPanel.tsx`

### Chat Services

- [Chat API](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/main.py): `chat-app/backend/app/main.py`
- [Chat Handler](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/routers/chat.py): `chat-app/backend/app/routers/chat.py`
- [Voice Live](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/routers/voice_live.py): `chat-app/backend/app/routers/voice_live.py`
- [Authentication](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/auth.py): `chat-app/backend/app/auth.py`
- [Scenario Config](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/scenario_config.py): `chat-app/backend/app/scenario_config.py`
- [Agent Orchestration](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/utils/foundry_agent_utils.py): `chat-app/backend/app/utils/foundry_agent_utils.py`

### Knowledge and Data

- **Azure AI Foundry**
- [Hybrid Search](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/services/search.py): `chat-app/backend/app/services/search.py`
- [Cosmos Data](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/cosmos_service.py): `chat-app/backend/app/cosmos_service.py`
- [Database Service](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/chat-app/backend/app/database.py): `chat-app/backend/app/database.py`
- [Host Data Store](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/scenario-app/backend/app/cosmos_service.py): `scenario-app/backend/app/cosmos_service.py`
- [Scenario Search](https://github.com/prachig-microsoft/customer-chatbot-solution-accelerator/blob/main/scenario-app/backend/app/services/search.py): `scenario-app/backend/app/services/search.py`

### Other components

- **Customer**

## Connections

- Customer → Scenario UI: browses (evidence: `README.md`)
- Customer → Chat Widget UI: asks questions (evidence: `README.md`)
- Scenario UI → Scenario API: requests data
- Scenario UI → Widget Embed: embeds (evidence: `README.md`)
- Widget Embed → Chat Widget UI: loads widget
- Chat Widget UI → Chat API: sends messages (evidence: `README.md`)
- Chat API → Chat Handler: registers routes (evidence: `chat-app/backend/app/main.py`)
- Chat API → Voice Live: registers routes (evidence: `chat-app/backend/app/main.py`)
- Scenario API → Domain APIs: registers routes (evidence: `scenario-app/backend/app/main.py`)
- Chat Handler → Authentication: checks identity (evidence: `chat-app/backend/app/routers/chat.py`)
- Voice Live → Authentication: checks identity (evidence: `chat-app/backend/app/routers/voice_live.py`)
- Chat Handler → Scenario Config: reads scenario (evidence: `chat-app/backend/app/routers/chat.py`)
- Voice Live → Scenario Config: reads scenario (evidence: `chat-app/backend/app/routers/voice_live.py`)
- Chat Handler → Agent Orchestration: invokes agents
- Voice Live → Agent Orchestration: uses grounding (evidence: `chat-app/backend/app/routers/voice_live.py`)
- Agent Orchestration → Azure AI Foundry: routes queries (evidence: `README.md`)
- Azure AI Foundry → Hybrid Search: retrieves knowledge (evidence: `README.md`)
- Hybrid Search → Azure AI Foundry: returns matches
- Chat Handler → Database Service: uses persistence (evidence: `chat-app/backend/app/routers/chat.py`)
- Database Service → Cosmos Data: selects implementation (evidence: `chat-app/backend/app/database.py`)
- Domain APIs → Host Data Store: uses data store
- Domain APIs → Scenario Search: uses search
- Scenario API → Scenario Config: selects scenario (evidence: `scenario-app/backend/app/main.py`)