# ananya-0607/telecom-support-assistant architecture

> Architecture diagram of the GitHub repository ananya-0607/telecom-support-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ananya-0607/telecom-support-assistant
- Repository: https://github.com/ananya-0607/telecom-support-assistant

## Overview

This is a local telecom-support resolution workspace: an agent submits a complaint, the backend classifies it, retrieves evidence, and drafts cited actions and questions for agent review. A separate knowledge-update path accepts tickets or PDFs and publishes searchable updates. The graph preserves documented evaluation and monitoring capabilities. Some subsystem links rely on the README or SOURCE INDEX; unsampled implementation details and unshown runtime wiring are not inferred.

Main entry points: [`src/telecom_support/ingestion/additions.py`](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/ingestion/additions.py) (Knowledge update jobs), [`src/telecom_support/api.py`](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/api.py) (FastAPI backend), [`src/telecom_support/pipeline.py`](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/pipeline.py) (Resolution pipeline), [`src/telecom_support/retrieval/service.py`](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/retrieval/service.py) (Evidence retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Agent workspace"]
  node_ui["Streamlit workspace<br/>[app.py]"]
  node_api["FastAPI backend<br/>[api.py]"]
end

subgraph group_resolution["Resolution workflow"]
  node_pipeline["Resolution pipeline<br/>[pipeline.py]"]
  node_taxonomy["Label taxonomy<br/>[taxonomy.py]"]
  node_classification["Complaint classification<br/>[service.py]"]
  node_class_schema["Classification schema<br/>[schemas.py]"]
  node_retrieval["Evidence retrieval<br/>[service.py]"]
  node_semantic["Semantic search<br/>[semantic.py]"]
  node_keyword["Keyword ranking<br/>[keyword.py]"]
  node_fusion["Rank fusion<br/>[ranking.py]"]
  node_generation["Grounded generation<br/>[service.py]"]
  node_generation_validation["Citation validation<br/>[validation.py]"]
end

subgraph group_knowledge["Knowledge and indexing"]
  node_ingestion_jobs["Knowledge update jobs<br/>[additions.py]"]
  node_pdf_extract["PDF extraction<br/>[pdf.py]"]
  node_chunking["Passage chunking<br/>[chunking.py]"]
  node_metadata["Passage labeling<br/>[metadata.py]"]
  node_ingestion_schema["Evidence records<br/>[schemas.py]"]
  node_embeddings["Text embeddings<br/>[embeddings.py]"]
  node_vector_store[("Qdrant vectors<br/>[vectors.py]")]
  node_record_builder["Index records<br/>[records.py]"]
  node_sql_store[("SQLite evidence store<br/>[storage.py]")]
end

subgraph group_operations["Operations and evaluation"]
  node_monitoring["Metrics and safe logs<br/>[monitoring.py]"]
  node_evaluation["RAG evaluation<br/>[rag.py]"]
  node_class_evaluation["Classification evaluation<br/>[classification.py]"]
end

node_agent(("Support agent"))
node_llm["Groq inference<br/>[llm.py]"]

node_agent -->|"submits complaint"| node_ui
node_ui -->|"sends requests"| node_api
node_api -->|"invokes"| node_pipeline
node_pipeline -->|"classifies"| node_classification
node_pipeline -->|"retrieves evidence"| node_retrieval
node_pipeline -->|"drafts resolution"| node_generation
node_pipeline -->|"checks token count"| node_chunking
node_pipeline -->|"reads taxonomy"| node_taxonomy
node_classification -->|"validates output"| node_class_schema
node_classification -->|"uses labels"| node_taxonomy
node_classification -->|"requests structured output"| node_llm
node_retrieval -->|"searches semantically"| node_semantic
node_retrieval -->|"ranks keywords"| node_keyword
node_retrieval -->|"combines ranks"| node_fusion
node_retrieval -->|"fetches evidence"| node_sql_store
node_semantic -->|"queries vectors"| node_vector_store
node_generation -->|"checks citations"| node_generation_validation
node_generation -->|"requests grounded draft"| node_llm
node_api -->|"submits updates"| node_ingestion_jobs
node_ingestion_jobs -->|"extracts PDF text"| node_pdf_extract
node_ingestion_jobs -->|"chunks passages"| node_chunking
node_ingestion_jobs -->|"labels passages"| node_metadata
node_ingestion_jobs -->|"builds records"| node_record_builder
node_ingestion_jobs -->|"publishes records"| node_sql_store
node_ingestion_jobs -->|"publishes vectors"| node_vector_store
node_ingestion_jobs -->|"updates labels"| node_taxonomy
node_record_builder -->|"validates records"| node_ingestion_schema
node_api -->|"records metrics"| node_monitoring
node_api -.->|"supports evaluation runs"| node_evaluation
node_api -.->|"supports evaluation runs"| node_class_evaluation
node_agent -.->|"reviews quality reports"| node_evaluation

click node_ui "https://github.com/ananya-0607/telecom-support-assistant/blob/main/app.py"
click node_api "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/api.py"
click node_pipeline "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/pipeline.py"
click node_taxonomy "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/taxonomy.py"
click node_classification "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/classification/service.py"
click node_class_schema "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/classification/schemas.py"
click node_retrieval "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/retrieval/service.py"
click node_semantic "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/retrieval/semantic.py"
click node_keyword "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/retrieval/keyword.py"
click node_fusion "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/retrieval/ranking.py"
click node_generation "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/generation/service.py"
click node_generation_validation "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/generation/validation.py"
click node_llm "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/llm.py"
click node_ingestion_jobs "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/ingestion/additions.py"
click node_pdf_extract "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/ingestion/pdf.py"
click node_chunking "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/ingestion/chunking.py"
click node_metadata "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/ingestion/metadata.py"
click node_ingestion_schema "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/ingestion/schemas.py"
click node_embeddings "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/indexing/embeddings.py"
click node_vector_store "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/indexing/vectors.py"
click node_record_builder "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/indexing/records.py"
click node_sql_store "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/indexing/storage.py"
click node_monitoring "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/monitoring.py"
click node_evaluation "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/evaluation/rag.py"
click node_class_evaluation "https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/evaluation/classification.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_ui,node_api toneBlue
class node_pipeline,node_taxonomy,node_classification,node_class_schema,node_retrieval,node_semantic,node_keyword,node_fusion,node_generation,node_generation_validation toneAmber
class node_ingestion_jobs,node_pdf_extract,node_chunking,node_metadata,node_ingestion_schema,node_embeddings,node_vector_store,node_record_builder,node_sql_store toneMint
class node_monitoring,node_evaluation,node_class_evaluation toneRose
class node_agent,node_llm toneIndigo
```

## Components

### Agent workspace

- [Streamlit workspace](https://github.com/ananya-0607/telecom-support-assistant/blob/main/app.py): `app.py`
- [FastAPI backend](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/api.py): `src/telecom_support/api.py`

### Resolution workflow

- [Resolution pipeline](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/pipeline.py): `src/telecom_support/pipeline.py`
- [Label taxonomy](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/taxonomy.py): `src/telecom_support/taxonomy.py`
- [Complaint classification](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/classification/service.py): `src/telecom_support/classification/service.py`
- [Classification schema](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/classification/schemas.py): `src/telecom_support/classification/schemas.py`
- [Evidence retrieval](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/retrieval/service.py): `src/telecom_support/retrieval/service.py`
- [Semantic search](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/retrieval/semantic.py): `src/telecom_support/retrieval/semantic.py`
- [Keyword ranking](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/retrieval/keyword.py): `src/telecom_support/retrieval/keyword.py`
- [Rank fusion](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/retrieval/ranking.py): `src/telecom_support/retrieval/ranking.py`
- [Grounded generation](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/generation/service.py): `src/telecom_support/generation/service.py`
- [Citation validation](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/generation/validation.py): `src/telecom_support/generation/validation.py`

### Knowledge and indexing

- [Knowledge update jobs](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/ingestion/additions.py): `src/telecom_support/ingestion/additions.py`
- [PDF extraction](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/ingestion/pdf.py): `src/telecom_support/ingestion/pdf.py`
- [Passage chunking](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/ingestion/chunking.py): `src/telecom_support/ingestion/chunking.py`
- [Passage labeling](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/ingestion/metadata.py): `src/telecom_support/ingestion/metadata.py`
- [Evidence records](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/ingestion/schemas.py): `src/telecom_support/ingestion/schemas.py`
- [Text embeddings](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/indexing/embeddings.py): `src/telecom_support/indexing/embeddings.py`
- [Qdrant vectors](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/indexing/vectors.py): `src/telecom_support/indexing/vectors.py`
- [Index records](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/indexing/records.py): `src/telecom_support/indexing/records.py`
- [SQLite evidence store](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/indexing/storage.py): `src/telecom_support/indexing/storage.py`

### Operations and evaluation

- [Metrics and safe logs](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/monitoring.py): `src/telecom_support/monitoring.py`
- [RAG evaluation](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/evaluation/rag.py): `src/telecom_support/evaluation/rag.py`
- [Classification evaluation](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/evaluation/classification.py): `src/telecom_support/evaluation/classification.py`

### Other components

- **Support agent**
- [Groq inference](https://github.com/ananya-0607/telecom-support-assistant/blob/main/src/telecom_support/llm.py): `src/telecom_support/llm.py`

## Connections

- Support agent → Streamlit workspace: submits complaint
- Streamlit workspace → FastAPI backend: sends requests
- FastAPI backend → Resolution pipeline: invokes (evidence: `src/telecom_support/api.py`)
- Resolution pipeline → Complaint classification: classifies (evidence: `src/telecom_support/pipeline.py`)
- Resolution pipeline → Evidence retrieval: retrieves evidence (evidence: `src/telecom_support/pipeline.py`)
- Resolution pipeline → Grounded generation: drafts resolution (evidence: `src/telecom_support/pipeline.py`)
- Resolution pipeline → Passage chunking: checks token count (evidence: `src/telecom_support/pipeline.py`)
- Resolution pipeline → Label taxonomy: reads taxonomy (evidence: `src/telecom_support/pipeline.py`)
- Complaint classification → Classification schema: validates output (evidence: `src/telecom_support/classification/service.py`)
- Complaint classification → Label taxonomy: uses labels (evidence: `src/telecom_support/classification/service.py`)
- Complaint classification → Groq inference: requests structured output (evidence: `src/telecom_support/pipeline.py`)
- Evidence retrieval → Semantic search: searches semantically (evidence: `src/telecom_support/retrieval/service.py`)
- Evidence retrieval → Keyword ranking: ranks keywords (evidence: `src/telecom_support/retrieval/service.py`)
- Evidence retrieval → Rank fusion: combines ranks (evidence: `src/telecom_support/retrieval/service.py`)
- Evidence retrieval → SQLite evidence store: fetches evidence (evidence: `src/telecom_support/retrieval/service.py`)
- Semantic search → Qdrant vectors: queries vectors (evidence: `src/telecom_support/retrieval/semantic.py`)
- Grounded generation → Citation validation: checks citations (evidence: `src/telecom_support/generation/service.py`)
- Grounded generation → Groq inference: requests grounded draft (evidence: `src/telecom_support/generation/service.py`)
- FastAPI backend → Knowledge update jobs: submits updates (evidence: `src/telecom_support/api.py`)
- Knowledge update jobs → PDF extraction: extracts PDF text (evidence: `src/telecom_support/ingestion/additions.py`)
- Knowledge update jobs → Passage chunking: chunks passages (evidence: `src/telecom_support/ingestion/additions.py`)
- Knowledge update jobs → Passage labeling: labels passages (evidence: `src/telecom_support/ingestion/additions.py`)
- Knowledge update jobs → Index records: builds records (evidence: `src/telecom_support/ingestion/additions.py`)
- Knowledge update jobs → SQLite evidence store: publishes records (evidence: `src/telecom_support/ingestion/additions.py`)
- Knowledge update jobs → Qdrant vectors: publishes vectors (evidence: `src/telecom_support/ingestion/additions.py`)
- Knowledge update jobs → Label taxonomy: updates labels (evidence: `src/telecom_support/ingestion/additions.py`)
- Index records → Evidence records: validates records (evidence: `src/telecom_support/indexing/records.py`)
- FastAPI backend → Metrics and safe logs: records metrics (evidence: `src/telecom_support/api.py`)
- FastAPI backend → RAG evaluation: supports evaluation runs
- FastAPI backend → Classification evaluation: supports evaluation runs
- Support agent → RAG evaluation: reviews quality reports
