# nurzhan-it/aitu_ai_chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/nurzhan-it/aitu_ai_chatbot
- Repository: https://github.com/nurzhan-it/aitu_ai_chatbot

## Overview

AITU Chatbot is a multilingual Telegram advising bot for AITU students, gated by university-email verification. Its main workflow is student question → clarification/triage when needed → document retrieval → sourced answer and feedback. Admins can ingest and manage documents, FAQs, and duplicate warnings. The graph includes the documented ingestion and duplicate-management capabilities; some internal calls are omitted where excerpts do not establish their direction.

Main entry points: [`bot/handlers/user.py`](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/handlers/user.py) (User handlers), [`bot/main.py`](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/main.py) (Bot dispatcher), [`bot/handlers/admin.py`](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/handlers/admin.py) (Document admin), [`ingestion/ingest.py`](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/ingestion/ingest.py) (Document ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["Bot experience"]
  node_dispatcher["Bot dispatcher<br/>[main.py]"]
  node_auth["Email verification<br/>[handler.py]"]
  node_user_handlers["User handlers<br/>[user.py]"]
  node_faq_handlers["FAQ management<br/>[admin_faq.py]"]
  node_faq_store[("FAQ repository<br/>[faq_repository.py]")]
  node_feedback["Feedback capture<br/>[feedback.py]"]
end

subgraph group_rag["Question answering"]
  node_dialog["Clarification dialog<br/>[dialog.py]"]
  node_triage["Question triage<br/>[triage.py]"]
  node_dialog_tools["Dialog helpers"]
  node_retriever["Hybrid retrieval<br/>[retriever.py]"]
  node_embedder["Text embeddings<br/>[embedder.py]"]
  node_generator["Answer generation<br/>[generator.py]"]
  node_answer_checks["Answer checks"]
end

subgraph group_docs["Document knowledge"]
  node_qdrant[("Vector collection")]
  node_ingest["Document ingestion<br/>[ingest.py]"]
  node_page_processing["Page processing<br/>[page_processor.py]"]
  node_vision["Scanned-page vision"]
end

subgraph group_admin["Administration"]
  node_admin_handlers["Document admin<br/>[admin.py]"]
  node_duplicate_detector["Duplicate detection<br/>[detector.py]"]
  node_warning_store[("Warning history<br/>[repository.py]")]
  node_report["Warning reports"]
  node_notifier["Duplicate notifications<br/>[notifier.py]"]
  node_sqlite[("SQLite records<br/>[db.py]")]
end

node_student(("Student"))
node_admin_user(("Admin"))
node_telegram["Telegram"]
node_email["Brevo email"]

node_student -->|"sends questions"| node_telegram
node_admin_user -->|"manages documents"| node_telegram
node_telegram -->|"delivers updates"| node_dispatcher
node_dispatcher -->|"registers first"| node_auth
node_dispatcher -->|"registers"| node_user_handlers
node_dispatcher -->|"registers"| node_dialog
node_dispatcher -->|"registers"| node_admin_handlers
node_auth -->|"sends codes"| node_email
node_user_handlers -->|"classifies questions"| node_triage
node_user_handlers -->|"starts clarification"| node_dialog
node_dialog -->|"uses dialog stages"| node_dialog_tools
node_user_handlers -->|"searches documents"| node_retriever
node_retriever -->|"embeds queries"| node_embedder
node_retriever -->|"searches vectors"| node_qdrant
node_user_handlers -->|"generates response"| node_generator
node_generator -->|"verifies citations"| node_answer_checks
node_user_handlers -->|"collects feedback"| node_feedback
node_user_handlers -->|"reads FAQ"| node_faq_store
node_faq_handlers -->|"edits FAQ"| node_faq_store
node_admin_handlers -->|"uploads documents"| node_ingest
node_ingest -->|"processes pages"| node_page_processing
node_page_processing -->|"routes scanned pages"| node_vision
node_ingest -->|"embeds chunks"| node_embedder
node_ingest -->|"upserts chunks"| node_qdrant
node_admin_handlers -->|"checks duplicates"| node_duplicate_detector
node_duplicate_detector -->|"records warnings"| node_warning_store
node_admin_handlers -->|"lists warnings"| node_warning_store
node_admin_handlers -->|"generates report"| node_report
node_duplicate_detector -->|"sends alerts"| node_notifier
node_warning_store -->|"persists records"| node_sqlite

click node_dispatcher "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/main.py"
click node_auth "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/auth/handler.py"
click node_user_handlers "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/handlers/user.py"
click node_dialog "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/handlers/dialog.py"
click node_triage "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/rag/dialog/triage.py"
click node_dialog_tools "https://github.com/nurzhan-it/aitu_ai_chatbot/tree/main/rag/dialog"
click node_retriever "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/rag/retriever.py"
click node_embedder "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/rag/embedder.py"
click node_generator "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/rag/generator.py"
click node_answer_checks "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/rag/citation_verifier.py"
click node_ingest "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/ingestion/ingest.py"
click node_page_processing "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/ingestion/page_processor.py"
click node_vision "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/ingestion/vision_processor.py"
click node_faq_handlers "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/handlers/admin_faq.py"
click node_faq_store "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/faq_repository.py"
click node_feedback "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/handlers/feedback.py"
click node_admin_handlers "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/handlers/admin.py"
click node_duplicate_detector "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/duplicate_detection/detector.py"
click node_warning_store "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/duplicate_detection/repository.py"
click node_report "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/duplicate_detection/report_generator.py"
click node_notifier "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/duplicate_detection/notifier.py"
click node_sqlite "https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/duplicate_detection/db.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_dispatcher,node_auth,node_user_handlers,node_faq_handlers,node_faq_store,node_feedback toneBlue
class node_dialog,node_triage,node_dialog_tools,node_retriever,node_embedder,node_generator,node_answer_checks toneAmber
class node_qdrant,node_ingest,node_page_processing,node_vision toneMint
class node_admin_handlers,node_duplicate_detector,node_warning_store,node_report,node_notifier,node_sqlite toneRose
class node_student,node_admin_user,node_telegram,node_email toneIndigo
```

## Components

### Bot experience

- [Bot dispatcher](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/main.py): `bot/main.py`
- [Email verification](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/auth/handler.py): `bot/auth/handler.py`
- [User handlers](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/handlers/user.py): `bot/handlers/user.py`
- [FAQ management](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/handlers/admin_faq.py): `bot/handlers/admin_faq.py`
- [FAQ repository](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/faq_repository.py): `bot/faq_repository.py`
- [Feedback capture](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/handlers/feedback.py): `bot/handlers/feedback.py`

### Question answering

- [Clarification dialog](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/handlers/dialog.py): `bot/handlers/dialog.py`
- [Question triage](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/rag/dialog/triage.py): `rag/dialog/triage.py`
- [Dialog helpers](https://github.com/nurzhan-it/aitu_ai_chatbot/tree/main/rag/dialog): `rag/dialog`
- [Hybrid retrieval](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/rag/retriever.py): `rag/retriever.py`
- [Text embeddings](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/rag/embedder.py): `rag/embedder.py`
- [Answer generation](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/rag/generator.py): `rag/generator.py`
- [Answer checks](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/rag/citation_verifier.py): `rag/citation_verifier.py`

### Document knowledge

- **Vector collection**
- [Document ingestion](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/ingestion/ingest.py): `ingestion/ingest.py`
- [Page processing](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/ingestion/page_processor.py): `ingestion/page_processor.py`
- [Scanned-page vision](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/ingestion/vision_processor.py): `ingestion/vision_processor.py`

### Administration

- [Document admin](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/bot/handlers/admin.py): `bot/handlers/admin.py`
- [Duplicate detection](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/duplicate_detection/detector.py): `duplicate_detection/detector.py`
- [Warning history](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/duplicate_detection/repository.py): `duplicate_detection/repository.py`
- [Warning reports](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/duplicate_detection/report_generator.py): `duplicate_detection/report_generator.py`
- [Duplicate notifications](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/duplicate_detection/notifier.py): `duplicate_detection/notifier.py`
- [SQLite records](https://github.com/nurzhan-it/aitu_ai_chatbot/blob/main/duplicate_detection/db.py): `duplicate_detection/db.py`

### Other components

- **Student**
- **Admin**
- **Telegram**
- **Brevo email**

## Connections

- Student → Telegram: sends questions (evidence: `README.md`)
- Admin → Telegram: manages documents (evidence: `README.md`)
- Telegram → Bot dispatcher: delivers updates (evidence: `README.md`)
- Bot dispatcher → Email verification: registers first (evidence: `bot/main.py`)
- Bot dispatcher → User handlers: registers (evidence: `bot/main.py`)
- Bot dispatcher → Clarification dialog: registers (evidence: `bot/main.py`)
- Bot dispatcher → Document admin: registers (evidence: `bot/main.py`)
- Email verification → Brevo email: sends codes (evidence: `bot/auth/handler.py`)
- User handlers → Question triage: classifies questions (evidence: `bot/handlers/user.py`)
- User handlers → Clarification dialog: starts clarification (evidence: `bot/handlers/user.py`)
- Clarification dialog → Dialog helpers: uses dialog stages (evidence: `bot/handlers/dialog.py`)
- User handlers → Hybrid retrieval: searches documents (evidence: `bot/handlers/user.py`)
- Hybrid retrieval → Text embeddings: embeds queries (evidence: `rag/retriever.py`)
- Hybrid retrieval → Vector collection: searches vectors (evidence: `README.md`)
- User handlers → Answer generation: generates response (evidence: `bot/handlers/user.py`)
- Answer generation → Answer checks: verifies citations (evidence: `rag/generator.py`)
- User handlers → Feedback capture: collects feedback (evidence: `bot/handlers/user.py`)
- User handlers → FAQ repository: reads FAQ (evidence: `bot/handlers/user.py`)
- FAQ management → FAQ repository: edits FAQ (evidence: `bot/handlers/admin_faq.py`)
- Document admin → Document ingestion: uploads documents (evidence: `bot/handlers/admin.py`)
- Document ingestion → Page processing: processes pages (evidence: `ingestion/ingest.py`)
- Page processing → Scanned-page vision: routes scanned pages (evidence: `ingestion/page_processor.py`)
- Document ingestion → Text embeddings: embeds chunks (evidence: `ingestion/ingest.py`)
- Document ingestion → Vector collection: upserts chunks (evidence: `ingestion/ingest.py`)
- Document admin → Duplicate detection: checks duplicates (evidence: `bot/handlers/admin.py`)
- Duplicate detection → Warning history: records warnings (evidence: `duplicate_detection/detector.py`)
- Document admin → Warning history: lists warnings (evidence: `bot/handlers/admin.py`)
- Document admin → Warning reports: generates report (evidence: `bot/handlers/admin.py`)
- Duplicate detection → Duplicate notifications: sends alerts (evidence: `duplicate_detection/detector.py`)
- Warning history → SQLite records: persists records (evidence: `duplicate_detection/repository.py`)
