# aldyar/umnico_bot architecture

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

- Interactive diagram: https://gitdiagram.com/aldyar/umnico_bot
- Repository: https://github.com/aldyar/umnico_bot

## Overview

This repository runs a PDR customer-service bot alongside a FastAPI webhook receiver. The main workflow accepts incoming Umnico messages, records them, waits for a quiet period, builds recent chat history, gets an AI response, and sends it back through Umnico; lead status and admin chat logs are also updated. A separate Telegram workflow lets admins browse accounts and edit their prompts. Some lead-management implementation was not sampled, so its storage wiring is shown only where the route’s calls and module names support it.

Main entry points: [`router/user.py`](https://github.com/aldyar/umnico_bot/blob/main/router/user.py) (Webhook API), [`main.py`](https://github.com/aldyar/umnico_bot/blob/main/main.py) (Application startup), [`database/models.py`](https://github.com/aldyar/umnico_bot/blob/main/database/models.py) (Database models), [`function/ai_function.py`](https://github.com/aldyar/umnico_bot/blob/main/function/ai_function.py) (AI responses)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application runtime"]
  node_main["Application startup<br/>[main.py]"]
  node_fastapi["Webhook API<br/>[user.py]"]
end

subgraph group_webhook["Webhook conversation"]
  node_timers["Conversation timers<br/>[storage.py]"]
  node_ai["AI responses<br/>[ai_function.py]"]
end

subgraph group_data["Persistence"]
  node_accounts["Account operations<br/>[account_func.py]"]
  node_leads["Lead operations<br/>[lead_func.py]"]
  node_messages["Message history<br/>[messages_func.py]"]
  node_models["Database models<br/>[models.py]"]
  node_database[("MySQL database")]
end

subgraph group_admin["Telegram administration"]
  node_telegram_handlers["Account controls<br/>[user.py]"]
  node_menu["Bot menu setup<br/>[command.py]"]
  node_admin_logs["Admin notifications<br/>[bot_request.py]"]
end

subgraph group_integrations["External services"]
  node_umnico_client["Umnico messaging<br/>[umnico_request.py]"]
  node_umnico(("Umnico platform"))
  node_openai(("OpenAI API"))
  node_telegram(("Telegram"))
end

node_customer(("Customer message"))
node_admin_user(("Admin user"))

node_main -->|"registers router"| node_fastapi
node_main -->|"registers handlers"| node_telegram_handlers
node_main -->|"initializes schema"| node_models
node_main -->|"sets commands"| node_menu
node_main -->|"starts polling"| node_telegram
node_customer -->|"sends message"| node_umnico
node_umnico -->|"posts webhook"| node_fastapi
node_fastapi -->|"checks account"| node_accounts
node_fastapi -->|"checks lead"| node_leads
node_fastapi -->|"records messages"| node_messages
node_fastapi -->|"tracks debounce"| node_timers
node_fastapi -->|"logs chat events"| node_admin_logs
node_fastapi -->|"requests image analysis"| node_ai
node_fastapi -->|"loads history"| node_messages
node_fastapi -->|"requests reply"| node_ai
node_fastapi -->|"sends reply"| node_umnico_client
node_fastapi -->|"updates lead status"| node_leads
node_ai -->|"requests completion"| node_openai
node_ai -->|"downloads image"| node_umnico
node_umnico_client -->|"posts message"| node_umnico
node_messages -->|"queries messages"| node_models
node_accounts -->|"queries accounts"| node_models
node_leads -->|"queries leads"| node_models
node_models -->|"reads and writes"| node_database
node_admin_user -->|"uses bot"| node_telegram
node_telegram -->|"dispatches updates"| node_telegram_handlers
node_telegram_handlers -->|"lists and edits"| node_accounts
node_admin_logs -->|"sends admin logs"| node_telegram

click node_main "https://github.com/aldyar/umnico_bot/blob/main/main.py"
click node_fastapi "https://github.com/aldyar/umnico_bot/blob/main/router/user.py"
click node_telegram_handlers "https://github.com/aldyar/umnico_bot/blob/main/handlers/user.py"
click node_menu "https://github.com/aldyar/umnico_bot/blob/main/app/command.py"
click node_timers "https://github.com/aldyar/umnico_bot/blob/main/app/storage.py"
click node_accounts "https://github.com/aldyar/umnico_bot/blob/main/function/account_func.py"
click node_leads "https://github.com/aldyar/umnico_bot/blob/main/function/lead_func.py"
click node_messages "https://github.com/aldyar/umnico_bot/blob/main/function/messages_func.py"
click node_models "https://github.com/aldyar/umnico_bot/blob/main/database/models.py"
click node_ai "https://github.com/aldyar/umnico_bot/blob/main/function/ai_function.py"
click node_umnico_client "https://github.com/aldyar/umnico_bot/blob/main/function/umnico_request.py"
click node_admin_logs "https://github.com/aldyar/umnico_bot/blob/main/handlers/bot_request.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_main,node_fastapi,node_admin_user toneBlue
class node_timers,node_ai toneAmber
class node_accounts,node_leads,node_messages,node_models,node_database toneMint
class node_telegram_handlers,node_menu,node_admin_logs toneRose
class node_umnico_client,node_umnico,node_openai,node_telegram,node_customer toneIndigo
```

## Components

### Application runtime

- [Application startup](https://github.com/aldyar/umnico_bot/blob/main/main.py): `main.py`
- [Webhook API](https://github.com/aldyar/umnico_bot/blob/main/router/user.py): `router/user.py`

### Webhook conversation

- [Conversation timers](https://github.com/aldyar/umnico_bot/blob/main/app/storage.py): `app/storage.py`
- [AI responses](https://github.com/aldyar/umnico_bot/blob/main/function/ai_function.py): `function/ai_function.py`

### Persistence

- [Account operations](https://github.com/aldyar/umnico_bot/blob/main/function/account_func.py): `function/account_func.py`
- [Lead operations](https://github.com/aldyar/umnico_bot/blob/main/function/lead_func.py): `function/lead_func.py`
- [Message history](https://github.com/aldyar/umnico_bot/blob/main/function/messages_func.py): `function/messages_func.py`
- [Database models](https://github.com/aldyar/umnico_bot/blob/main/database/models.py): `database/models.py`
- **MySQL database**

### Telegram administration

- [Account controls](https://github.com/aldyar/umnico_bot/blob/main/handlers/user.py): `handlers/user.py`
- [Bot menu setup](https://github.com/aldyar/umnico_bot/blob/main/app/command.py): `app/command.py`
- [Admin notifications](https://github.com/aldyar/umnico_bot/blob/main/handlers/bot_request.py): `handlers/bot_request.py`

### External services

- [Umnico messaging](https://github.com/aldyar/umnico_bot/blob/main/function/umnico_request.py): `function/umnico_request.py`
- **Umnico platform**
- **OpenAI API**
- **Telegram**

### Other components

- **Customer message**
- **Admin user**

## Connections

- Application startup → Webhook API: registers router
- Application startup → Account controls: registers handlers
- Application startup → Database models: initializes schema
- Application startup → Bot menu setup: sets commands
- Application startup → Telegram: starts polling
- Customer message → Umnico platform: sends message
- Umnico platform → Webhook API: posts webhook
- Webhook API → Account operations: checks account
- Webhook API → Lead operations: checks lead
- Webhook API → Message history: records messages
- Webhook API → Conversation timers: tracks debounce
- Webhook API → Admin notifications: logs chat events
- Webhook API → AI responses: requests image analysis
- Webhook API → Message history: loads history
- Webhook API → AI responses: requests reply
- Webhook API → Umnico messaging: sends reply
- Webhook API → Lead operations: updates lead status
- AI responses → OpenAI API: requests completion
- AI responses → Umnico platform: downloads image
- Umnico messaging → Umnico platform: posts message
- Message history → Database models: queries messages
- Account operations → Database models: queries accounts
- Lead operations → Database models: queries leads
- Database models → MySQL database: reads and writes
- Admin user → Telegram: uses bot
- Telegram → Account controls: dispatches updates
- Account controls → Account operations: lists and edits
- Admin notifications → Telegram: sends admin logs