# balta8/ai-telecom-assistant architecture

> Architecture diagram of the GitHub repository balta8/ai-telecom-assistant, 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/balta8/ai-telecom-assistant
- Repository: https://github.com/balta8/ai-telecom-assistant

## Overview

AI Telecom Assistant serves telecom customers through Chainlit or a console chat. Each message enters the session-aware agent, which dispatches it to FAQ, package-detail, recommendation, or technical-support tools; retrieval-backed tools use Chroma search, while the support tool answers from the conversation context. README also documents data chunking and Chroma ingestion as the knowledge-base setup path. The source excerpts establish the agent/tool/retrieval calls; the ingestion links are based on README instructions, and the FAQ and package tools use different retrieval paths.

Main entry points: [`agent.py`](https://github.com/balta8/ai-telecom-assistant/blob/main/agent.py) (Session Agent), [`utils/retrievers.py`](https://github.com/balta8/ai-telecom-assistant/blob/main/utils/retrievers.py) (Retriever Manager), [`src/nodes/faq_node.py`](https://github.com/balta8/ai-telecom-assistant/blob/main/src/nodes/faq_node.py) (FAQ Answers), [`src/nodes/package_recommendation_node.py`](https://github.com/balta8/ai-telecom-assistant/blob/main/src/nodes/package_recommendation_node.py) (Package Advice)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Chat Interfaces"]
  node_chainlit["Chainlit Chat<br/>[chainlit_app.py]"]
  node_console["Console Chat<br/>[app.py]"]
end

subgraph group_orchestration["Agent Orchestration"]
  node_agent["Session Agent<br/>[agent.py]"]
  node_config["Model Config<br/>[config.py]"]
end

subgraph group_customer_tools["Customer Tools"]
  node_faq["FAQ Answers<br/>[faq_node.py]"]
  node_package_info["Package Details"]
  node_recommendation["Package Advice"]
  node_support["Technical Support<br/>[support_node.py]"]
end

subgraph group_knowledge["Knowledge Retrieval"]
  node_retrievers["Retriever Manager<br/>[retrievers.py]"]
  node_chunking["Data Chunking<br/>[chunking.py]"]
  node_ingestion["Chroma Ingestion<br/>[ingest.py]"]
  node_chroma[("Chroma Store")]
end

node_customer(("Customer"))
node_openai["OpenAI Models"]

node_customer -->|"sends message"| node_chainlit
node_customer -->|"sends message"| node_console
node_chainlit -->|"handles message"| node_agent
node_console -->|"handles message"| node_agent
node_agent -->|"sets up"| node_retrievers
node_agent -->|"dispatches to"| node_faq
node_agent -->|"dispatches to"| node_package_info
node_agent -->|"dispatches to"| node_recommendation
node_agent -->|"dispatches to"| node_support
node_agent -->|"prompts"| node_openai
node_faq -->|"searches FAQs"| node_retrievers
node_faq -->|"generates answer"| node_openai
node_package_info -->|"searches packages"| node_retrievers
node_recommendation -->|"searches packages"| node_retrievers
node_recommendation -->|"generates advice"| node_openai
node_support -->|"generates guidance"| node_openai
node_retrievers -->|"searches vectors"| node_chroma
node_retrievers -->|"embeds queries"| node_openai
node_retrievers -->|"reranks results"| node_openai
node_chunking -->|"supplies chunks"| node_ingestion
node_ingestion -->|"writes documents"| node_chroma
node_ingestion -->|"embeds documents"| node_openai
node_config -.->|"configures models"| node_openai

click node_chainlit "https://github.com/balta8/ai-telecom-assistant/blob/main/chainlit_app.py"
click node_console "https://github.com/balta8/ai-telecom-assistant/blob/main/app.py"
click node_agent "https://github.com/balta8/ai-telecom-assistant/blob/main/agent.py"
click node_config "https://github.com/balta8/ai-telecom-assistant/blob/main/config.py"
click node_faq "https://github.com/balta8/ai-telecom-assistant/blob/main/src/nodes/faq_node.py"
click node_package_info "https://github.com/balta8/ai-telecom-assistant/blob/main/src/nodes/package_info_node.py"
click node_recommendation "https://github.com/balta8/ai-telecom-assistant/blob/main/src/nodes/package_recommendation_node.py"
click node_support "https://github.com/balta8/ai-telecom-assistant/blob/main/src/nodes/support_node.py"
click node_retrievers "https://github.com/balta8/ai-telecom-assistant/blob/main/utils/retrievers.py"
click node_chunking "https://github.com/balta8/ai-telecom-assistant/blob/main/utils/chunking.py"
click node_ingestion "https://github.com/balta8/ai-telecom-assistant/blob/main/utils/ingest.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_chainlit,node_console toneBlue
class node_agent,node_config toneAmber
class node_faq,node_package_info,node_recommendation,node_support toneMint
class node_retrievers,node_chunking,node_ingestion,node_chroma toneRose
class node_customer,node_openai toneIndigo
```

## Components

### Chat Interfaces

- [Chainlit Chat](https://github.com/balta8/ai-telecom-assistant/blob/main/chainlit_app.py): `chainlit_app.py`
- [Console Chat](https://github.com/balta8/ai-telecom-assistant/blob/main/app.py): `app.py`

### Agent Orchestration

- [Session Agent](https://github.com/balta8/ai-telecom-assistant/blob/main/agent.py): `agent.py`
- [Model Config](https://github.com/balta8/ai-telecom-assistant/blob/main/config.py): `config.py`

### Customer Tools

- [FAQ Answers](https://github.com/balta8/ai-telecom-assistant/blob/main/src/nodes/faq_node.py): `src/nodes/faq_node.py`
- [Package Details](https://github.com/balta8/ai-telecom-assistant/blob/main/src/nodes/package_info_node.py): `src/nodes/package_info_node.py`
- [Package Advice](https://github.com/balta8/ai-telecom-assistant/blob/main/src/nodes/package_recommendation_node.py): `src/nodes/package_recommendation_node.py`
- [Technical Support](https://github.com/balta8/ai-telecom-assistant/blob/main/src/nodes/support_node.py): `src/nodes/support_node.py`

### Knowledge Retrieval

- [Retriever Manager](https://github.com/balta8/ai-telecom-assistant/blob/main/utils/retrievers.py): `utils/retrievers.py`
- [Data Chunking](https://github.com/balta8/ai-telecom-assistant/blob/main/utils/chunking.py): `utils/chunking.py`
- [Chroma Ingestion](https://github.com/balta8/ai-telecom-assistant/blob/main/utils/ingest.py): `utils/ingest.py`
- **Chroma Store**

### Other components

- **Customer**
- **OpenAI Models**

## Connections

- Customer → Chainlit Chat: sends message (evidence: `chainlit_app.py`)
- Customer → Console Chat: sends message (evidence: `app.py`)
- Chainlit Chat → Session Agent: handles message (evidence: `chainlit_app.py`)
- Console Chat → Session Agent: handles message (evidence: `app.py`)
- Session Agent → Retriever Manager: sets up (evidence: `agent.py`)
- Session Agent → FAQ Answers: dispatches to (evidence: `agent.py`)
- Session Agent → Package Details: dispatches to (evidence: `agent.py`)
- Session Agent → Package Advice: dispatches to (evidence: `agent.py`)
- Session Agent → Technical Support: dispatches to (evidence: `agent.py`)
- Session Agent → OpenAI Models: prompts (evidence: `agent.py`)
- FAQ Answers → Retriever Manager: searches FAQs (evidence: `src/nodes/faq_node.py`)
- FAQ Answers → OpenAI Models: generates answer (evidence: `src/nodes/faq_node.py`)
- Package Details → Retriever Manager: searches packages (evidence: `src/nodes/package_info_node.py`)
- Package Advice → Retriever Manager: searches packages (evidence: `src/nodes/package_recommendation_node.py`)
- Package Advice → OpenAI Models: generates advice (evidence: `src/nodes/package_recommendation_node.py`)
- Technical Support → OpenAI Models: generates guidance (evidence: `src/nodes/support_node.py`)
- Retriever Manager → Chroma Store: searches vectors (evidence: `utils/retrievers.py`)
- Retriever Manager → OpenAI Models: embeds queries (evidence: `utils/retrievers.py`)
- Retriever Manager → OpenAI Models: reranks results (evidence: `utils/retrievers.py`)
- Data Chunking → Chroma Ingestion: supplies chunks (evidence: `README.md`)
- Chroma Ingestion → Chroma Store: writes documents (evidence: `utils/ingest.py`)
- Chroma Ingestion → OpenAI Models: embeds documents (evidence: `utils/ingest.py`)
- Model Config → OpenAI Models: configures models