# phucnguyenthanh04/telesale-sudocode2026 architecture

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

- Interactive diagram: https://gitdiagram.com/phucnguyenthanh04/telesale-sudocode2026
- Repository: https://github.com/phucnguyenthanh04/telesale-sudocode2026

## Overview

TeleSale combines a text sales-assistant workflow with voice access and a managed, reviewable knowledge base. A customer or operator reaches the backend, which forwards chat turns to the AI service; its harness runs an agent and invokes business capabilities through MCP. In parallel, knowledge evidence is ingested, reviewed and published for retrieval. The README documents four MCP services and speech capabilities, but excerpts do not expose every wiring detail, so uncertain runtime links are omitted. This map focuses on product runtime, not evaluation tooling.

Main entry points: [`ai-services/app/agent/mcp/gateway.py`](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/agent/mcp/gateway.py) (MCP gateway), [`ai-services/app/agent/harness/runtime.py`](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/agent/harness/runtime.py) (Agent harness), [`ai-services/app/mcp_servers/mcp_knowledge/services/knowledge.py`](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/mcp_servers/mcp_knowledge/services/knowledge.py) (Policy retrieval), [`backend/app/api/text.py`](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/backend/app/api/text.py) (Chat route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_backend["Backend API<br/>[main.py]"]
  node_backend_chat["Chat route<br/>[text.py]"]
  node_frontend["Web client<br/>[chat.js]"]
  node_voice_gateway["Voice gateway<br/>[voice_main.py]"]
end

subgraph group_agent["AI conversation"]
  node_ai_api["AI chat API<br/>[chat.py]"]
  node_chat["Chat turn<br/>[chat.py]"]
  node_runtime["Agent harness<br/>[runtime.py]"]
  node_guardrails["Guardrails<br/>[checks.py]"]
  node_gateway["MCP gateway<br/>[gateway.py]"]
end

subgraph group_business["Business MCP"]
  node_catalog["Catalog tools<br/>[handlers.py]"]
  node_orders["Order tools<br/>[handlers.py]"]
  node_memory["Memory service<br/>[server.py]"]
end

subgraph group_knowledge["Knowledge lifecycle"]
  node_knowledge_api["Knowledge API<br/>[knowledge.py]"]
  node_knowledge_events["Evidence events<br/>[ingest.py]"]
  node_knowledge_worker["Knowledge worker<br/>[worker.py]"]
  node_knowledge_services["Review and release"]
  node_knowledge_mcp["Knowledge MCP<br/>[server.py]"]
  node_policy_search["Policy retrieval<br/>[knowledge.py]"]
  node_hybrid_index[("Hybrid index<br/>[qdrant.py]")]
  node_policy_data[("Policy database<br/>[postgres.py]")]
end

subgraph group_speech["Speech"]
  node_speech_api["Speech API<br/>[app.py]"]
  node_speech_service["Speech service<br/>[voice_speech.py]"]
end

node_customer(("Customer / operator"))
node_source_data["BTC source data"]

node_customer -->|"uses"| node_frontend
node_frontend -.->|"submits turns"| node_backend_chat
node_backend -->|"routes chat"| node_backend_chat
node_backend_chat -->|"forwards turns"| node_ai_api
node_ai_api -->|"calls"| node_chat
node_chat -->|"runs turn"| node_runtime
node_runtime -.->|"checks"| node_guardrails
node_runtime -.->|"invokes tools"| node_gateway
node_gateway -.->|"dispatches"| node_catalog
node_gateway -.->|"dispatches"| node_orders
node_gateway -.->|"dispatches"| node_memory
node_gateway -.->|"dispatches"| node_knowledge_mcp
node_knowledge_api -.->|"records evidence"| node_knowledge_events
node_knowledge_events -.->|"queues work"| node_knowledge_worker
node_knowledge_worker -.->|"processes lifecycle"| node_knowledge_services
node_knowledge_services -.->|"persists releases"| node_policy_data
node_knowledge_mcp -->|"creates service"| node_policy_search
node_policy_search -.->|"queries index"| node_hybrid_index
node_policy_search -.->|"reads policy"| node_policy_data
node_source_data -.->|"supplies evidence"| node_knowledge_events
node_customer -.->|"starts voice"| node_voice_gateway
node_voice_gateway -.->|"requests speech"| node_speech_service
node_speech_service -.->|"calls speech endpoint"| node_speech_api

click node_backend "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/backend/app/main.py"
click node_backend_chat "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/backend/app/api/text.py"
click node_frontend "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/frontend/chat.js"
click node_ai_api "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/api/chat.py"
click node_chat "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/agent/chat.py"
click node_runtime "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/agent/harness/runtime.py"
click node_guardrails "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/agent/guardrails/checks.py"
click node_gateway "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/agent/mcp/gateway.py"
click node_catalog "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/mcp_servers/mcp_catalog/tools/handlers.py"
click node_orders "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/mcp_servers/mcp_order/tools/handlers.py"
click node_memory "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/mcp_servers/mcp_memory/server.py"
click node_knowledge_api "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/api/knowledge.py"
click node_knowledge_events "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/knowledge/events/ingest.py"
click node_knowledge_worker "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/knowledge/events/worker.py"
click node_knowledge_services "https://github.com/phucnguyenthanh04/telesale-sudocode2026/tree/main/ai-services/app/knowledge/services"
click node_knowledge_mcp "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/mcp_servers/mcp_knowledge/server.py"
click node_policy_search "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/mcp_servers/mcp_knowledge/services/knowledge.py"
click node_hybrid_index "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/mcp_servers/mcp_knowledge/repos/qdrant.py"
click node_policy_data "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/knowledge/repos/postgres.py"
click node_speech_api "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/speech/serving/app.py"
click node_speech_service "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/backend/app/services/voice_speech.py"
click node_voice_gateway "https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/backend/app/voice_main.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_backend,node_backend_chat,node_frontend,node_voice_gateway toneBlue
class node_ai_api,node_chat,node_runtime,node_guardrails,node_gateway toneAmber
class node_catalog,node_orders,node_memory toneMint
class node_knowledge_api,node_knowledge_events,node_knowledge_worker,node_knowledge_services,node_knowledge_mcp,node_policy_search,node_hybrid_index,node_policy_data toneRose
class node_speech_api,node_speech_service,node_customer,node_source_data toneIndigo
```

## Components

### User interaction

- [Backend API](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/backend/app/main.py): `backend/app/main.py`
- [Chat route](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/backend/app/api/text.py): `backend/app/api/text.py`
- [Web client](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/frontend/chat.js): `frontend/chat.js`
- [Voice gateway](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/backend/app/voice_main.py): `backend/app/voice_main.py`

### AI conversation

- [AI chat API](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/api/chat.py): `ai-services/app/api/chat.py`
- [Chat turn](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/agent/chat.py): `ai-services/app/agent/chat.py`
- [Agent harness](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/agent/harness/runtime.py): `ai-services/app/agent/harness/runtime.py`
- [Guardrails](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/agent/guardrails/checks.py): `ai-services/app/agent/guardrails/checks.py`
- [MCP gateway](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/agent/mcp/gateway.py): `ai-services/app/agent/mcp/gateway.py`

### Business MCP

- [Catalog tools](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/mcp_servers/mcp_catalog/tools/handlers.py): `ai-services/app/mcp_servers/mcp_catalog/tools/handlers.py`
- [Order tools](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/mcp_servers/mcp_order/tools/handlers.py): `ai-services/app/mcp_servers/mcp_order/tools/handlers.py`
- [Memory service](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/mcp_servers/mcp_memory/server.py): `ai-services/app/mcp_servers/mcp_memory/server.py`

### Knowledge lifecycle

- [Knowledge API](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/api/knowledge.py): `ai-services/app/api/knowledge.py`
- [Evidence events](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/knowledge/events/ingest.py): `ai-services/app/knowledge/events/ingest.py`
- [Knowledge worker](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/knowledge/events/worker.py): `ai-services/app/knowledge/events/worker.py`
- [Review and release](https://github.com/phucnguyenthanh04/telesale-sudocode2026/tree/main/ai-services/app/knowledge/services): `ai-services/app/knowledge/services`
- [Knowledge MCP](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/mcp_servers/mcp_knowledge/server.py): `ai-services/app/mcp_servers/mcp_knowledge/server.py`
- [Policy retrieval](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/mcp_servers/mcp_knowledge/services/knowledge.py): `ai-services/app/mcp_servers/mcp_knowledge/services/knowledge.py`
- [Hybrid index](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/mcp_servers/mcp_knowledge/repos/qdrant.py): `ai-services/app/mcp_servers/mcp_knowledge/repos/qdrant.py`
- [Policy database](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/ai-services/app/knowledge/repos/postgres.py): `ai-services/app/knowledge/repos/postgres.py`

### Speech

- [Speech API](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/speech/serving/app.py): `speech/serving/app.py`
- [Speech service](https://github.com/phucnguyenthanh04/telesale-sudocode2026/blob/main/backend/app/services/voice_speech.py): `backend/app/services/voice_speech.py`

### Other components

- **Customer / operator**
- **BTC source data**

## Connections

- Customer / operator → Web client: uses (evidence: `README.md`)
- Web client → Chat route: submits turns
- Backend API → Chat route: routes chat (evidence: `backend/app/main.py`)
- Chat route → AI chat API: forwards turns (evidence: `README.md`)
- AI chat API → Chat turn: calls (evidence: `ai-services/app/api/chat.py`)
- Chat turn → Agent harness: runs turn (evidence: `ai-services/app/api/chat.py`)
- Agent harness → Guardrails: checks
- Agent harness → MCP gateway: invokes tools
- MCP gateway → Catalog tools: dispatches
- MCP gateway → Order tools: dispatches
- MCP gateway → Memory service: dispatches
- MCP gateway → Knowledge MCP: dispatches
- Knowledge API → Evidence events: records evidence
- Evidence events → Knowledge worker: queues work
- Knowledge worker → Review and release: processes lifecycle
- Review and release → Policy database: persists releases
- Knowledge MCP → Policy retrieval: creates service (evidence: `ai-services/app/mcp_servers/mcp_knowledge/server.py`)
- Policy retrieval → Hybrid index: queries index
- Policy retrieval → Policy database: reads policy
- BTC source data → Evidence events: supplies evidence
- Customer / operator → Voice gateway: starts voice
- Voice gateway → Speech service: requests speech
- Speech service → Speech API: calls speech endpoint
