# azure-samples/realtime-call-center-accelerator architecture

> Architecture diagram of the GitHub repository azure-samples/realtime-call-center-accelerator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azure-samples/realtime-call-center-accelerator
- Repository: https://github.com/azure-samples/realtime-call-center-accelerator

## Overview

##### Project Type and Purpose
- This is a full-stack Azure Solution Accelerator that demonstrates an AI-assisted, phone-based call center using Azure Communication Services (ACS), Azure Container Apps, Azure AI Search, and OpenAI models.
- It provides both a browser-based UI and a telephone interface to interact with an AI agent, backed by a Python Flask-style API.

##### Main Architectural Components
A. Client Layer
– Web browser UI: static assets (index.html, app.js, style.css) served by the container app.
– Telephone endpoint: Customer dials ACS-provisioned phone number.
B. API & Business Logic (deployed as Azure Container App)
– app.py: Flask-style HTTP API for web UI and Event Grid webhooks.
– Backend modules (acs.py, azure.py, rtmt.py, helpers.py): handle ACS call control, RTM streaming websocket, metadata.
– RAG tooling (tools/rag/ai_search.py): calls Azure AI Search + OpenAI to generate agent responses.
C. Azure Platform Services
1. Azure Container Apps
- Hosts the API & static web UI.
- Exposes HTTP endpoint (/acs, /realtime-acs).
2. Azure Communication Services (ACS)
- Phone number resource receives inbound calls.
- Media streaming channel (WebSocket) to backend.
3. Azure Event Grid
- Subscribes to ACS “Incoming Call” events.
- Forwards event to backend webhook.
4. Azure Storage + AI Search
- Storage Account “prompt” container: optional system_prompt.md override.
- Storage Account “data” container: knowledge-base files (in /data).
- Azure AI Search indexes and vectorizes knowledge base.
5. OpenAI Service
- Processes RAG queries and returns chat completions.
D. Infrastructure as Code
– Bicep templates (`infra/**/*.bicep`): define all above resources.
– Scripts (`azd-hooks/deploy.sh`): build & deploy container, copy data to storage.

##### Relationships & Data Flows
1. Web UI → HTTP POST → API → RAG / OpenAI → API → WebSocket or HTTP response → Web UI.
2. Phone call → ACS → Event Grid → API webhook (/acs/incoming) → API answers call (via ACS SDK) → API initiates media stream over WebSocket (/realtime-acs) → API sends/receives speech frames → RAG/AI Search/OpenAI → API streams back responses → ACS → caller’s phone.
3. Deployment: `azd up` → Bicep templates → provision ACS, Container Apps, Storage, AI Search, Event Grid.
4. Data upload: `scripts/upload_data.sh` → Azure Storage → AI Search indexer runs.

##### Architectural Patterns & Principles
– Serverless / container-based microservices: stateless container app hosts API and UI.
– Event-driven design: Event Grid routes ACS events to the API.
– Real-time streaming: WebSocket integration with ACS for bi-directional media.
– RAG (Retrieval-Augmented Generation): calling AI Search to retrieve docs, then OpenAI for generation.
– Infrastructure as Code: all cloud resources defined as Bicep modules.

##### Final Touches
- Number the main flow steps if desired.
- Keep labels concise but specific (e.g., “Container App (Flask API + UI)”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer" 
        direction TB
        UI["Web Browser UI (Static Assets)"]:::client
        Phone["Telephone Endpoint (ACS)"]:::client
    end

    subgraph "Container App (API + UI)" 
        direction TB
        API["Flask API (src/app/app.py)"]:::container
        acs_module["ACS Call Control (acs.py)"]:::container
        rtmt_module["RTM Streaming WebSocket (rtmt.py)"]:::container
        azure_metadata["Azure Metadata Module (azure.py)"]:::container
        helpers_module["Helpers Module (helpers.py)"]:::container
        rag_module["RAG Tooling (ai_search.py)"]:::container
        tools_module["General Tools (tools.py)"]:::container
        requirements["Requirements Manifest (requirements.txt)"]:::container
        prompt_override["Custom Prompt Override (system_prompt.md)"]:::container
        data_folder["Data Folder (data/)"]:::container
    end

    subgraph "Azure PaaS Services"
        direction TB
        ACS_service["Azure Communication Services"]:::paas
        EventGrid["Azure Event Grid"]:::paas
        Storage["Azure Storage"]:::paas
        AISearch["Azure AI Search"]:::paas
    end

    subgraph "AI Services"
        direction TB
        OpenAI["OpenAI Service"]:::external
    end

    subgraph "Infrastructure as Code"
        direction TB
        bicep["Bicep Templates (infra/main.bicep)"]:::infra
        infra_scripts["Deployment Scripts (azd-hooks/)"]:::infra
        data_upload["Data Upload Script (scripts/upload_data.sh)"]:::infra
        definitions["AI Search Index Definitions (infra/definitions/index.json)"]:::infra
    end

    %% Client to API Web Flow
    UI -->|HTTP POST| API
    API -->|calls RAG| rag_module
    rag_module -->|HTTP| AISearch
    AISearch -->|results| rag_module
    rag_module -->|calls OpenAI| OpenAI
    OpenAI -->|response| rag_module
    rag_module -->|response| API
    API -->|HTTP/WebSocket| UI

    %% Phone Call Flow
    Phone -->|Inbound Call| ACS_service
    ACS_service -->|Event| EventGrid
    EventGrid -.->|HTTP POST /acs/incoming| API
    API -->|Answer Call| acs_module
    acs_module -->|Initiate WebSocket /realtime-acs| rtmt_module
    rtmt_module -->|speech frames| rag_module
    rag_module -->|response frames| rtmt_module
    rtmt_module -->|media stream| ACS_service
    ACS_service -->|to Caller| Phone

    %% Infra Relationships
    infra_scripts --> bicep
    bicep --> ACS_service
    bicep --> API
    bicep --> Storage
    bicep --> AISearch
    bicep --> EventGrid
    data_upload --> Storage

    %% Click Events
    click UI "https://github.com/azure-samples/realtime-call-center-accelerator/blob/main/src/app/static/index.html"
    click API "https://github.com/azure-samples/realtime-call-center-accelerator/blob/main/src/app/app.py"
    click acs_module "https://github.com/azure-samples/realtime-call-center-accelerator/blob/main/src/app/backend/acs.py"
    click rtmt_module "https://github.com/azure-samples/realtime-call-center-accelerator/blob/main/src/app/backend/rtmt.py"
    click azure_metadata "https://github.com/azure-samples/realtime-call-center-accelerator/blob/main/src/app/backend/azure.py"
    click helpers_module "https://github.com/azure-samples/realtime-call-center-accelerator/blob/main/src/app/backend/helpers.py"
    click rag_module "https://github.com/azure-samples/realtime-call-center-accelerator/blob/main/src/app/backend/tools/rag/ai_search.py"
    click tools_module "https://github.com/azure-samples/realtime-call-center-accelerator/blob/main/src/app/backend/tools/tools.py"
    click requirements "https://github.com/azure-samples/realtime-call-center-accelerator/blob/main/src/app/requirements.txt"
    click prompt_override "https://github.com/azure-samples/realtime-call-center-accelerator/blob/main/src/app/system_prompt.md"
    click data_folder "https://github.com/azure-samples/realtime-call-center-accelerator/tree/main/data/"
    click infra_scripts "https://github.com/azure-samples/realtime-call-center-accelerator/blob/main/azd-hooks/deploy.sh"
    click bicep "https://github.com/azure-samples/realtime-call-center-accelerator/blob/main/infra/main.bicep"
    click data_upload "https://github.com/azure-samples/realtime-call-center-accelerator/blob/main/scripts/upload_data.sh"
    click definitions "https://github.com/azure-samples/realtime-call-center-accelerator/blob/main/infra/definitions/index.json"

    %% Styles
    classDef client fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1;
    classDef container fill:#E8F5E9,stroke:#66BB6A,color:#1B5E20;
    classDef paas fill:#FFF3E0,stroke:#FFA726,color:#E65100;
    classDef external fill:#F3E5F5,stroke:#BA68C8,color:#4A148C,stroke-dasharray: 5 5;
    classDef infra fill:#ECEFF1,stroke:#90A4AE,color:#37474F;
```
