# murodovdev/telegram_job_bot architecture

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

- Interactive diagram: https://gitdiagram.com/murodovdev/telegram_job_bot
- Repository: https://github.com/murodovdev/telegram_job_bot

## Overview

This is a Telegram job-aggregation bot: two Telethon accounts monitor Uzbek community groups through real-time events and backup polling, filter and deduplicate posts, then publish qualifying jobs to a target group. AI halal screening runs asynchronously after forwarding; flagged posts can be removed and queued for admin review. A separate aiogram panel manages groups and settings, while a daily scheduler reports statistics. The graph preserves documented lifecycle features as well. Relationships are based on the supplied excerpts, SOURCE INDEX references, and README; unsampled implementation details are not inferred.

Main entry points: [`bot/monitor.py`](https://github.com/murodovdev/telegram_job_bot/blob/main/bot/monitor.py) (Event and polling monitor), [`bot/admin_bot.py`](https://github.com/murodovdev/telegram_job_bot/blob/main/bot/admin_bot.py) (Admin control panel), [`main.py`](https://github.com/murodovdev/telegram_job_bot/blob/main/main.py) (Application startup), [`bot/database.py`](https://github.com/murodovdev/telegram_job_bot/blob/main/bot/database.py) (SQLite state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_entry["Application startup<br/>[main.py]"]
  node_clients["Dual clients<br/>[client.py]"]
end

subgraph group_processing["Job Processing"]
  node_monitor["Event and polling monitor<br/>[monitor.py]"]
  node_keywords["Job keyword detection<br/>[filters.py]"]
  node_halal_keywords["Halal keyword screening<br/>[halal_filter.py]"]
  node_ai_screen["AI halal screening<br/>[groq_halal.py]"]
  node_lifecycle["Post review and group lifecycle<br/>[monitor.py]"]
end

subgraph group_operations["Admin Operations"]
  node_admin_panel["Admin control panel<br/>[admin_bot.py]"]
  node_scheduler["Daily summary scheduler<br/>[scheduler.py]"]
  node_notifier["Admin notifications<br/>[notifier.py]"]
end

subgraph group_state["State and Delivery"]
  node_database[("SQLite state<br/>[database.py]")]
  node_delivery["Formatting and rate-limited sending<br/>[utils.py]"]
end

node_admin(("Administrator"))
node_telegram{{"Telegram"}}
node_groq_api{{"Groq API"}}

node_admin -->|"manages bot"| node_admin_panel
node_telegram -->|"provides updates"| node_clients
node_entry -->|"initializes"| node_database
node_entry -->|"starts"| node_monitor
node_entry -->|"starts task"| node_admin_panel
node_entry -->|"starts task"| node_scheduler
node_entry -->|"keeps connected"| node_clients
node_monitor -->|"registers handlers"| node_clients
node_clients -->|"connects accounts"| node_telegram
node_monitor -->|"checks messages"| node_keywords
node_monitor -->|"screens jobs"| node_halal_keywords
node_monitor -->|"checks and records"| node_database
node_monitor -->|"formats and sends"| node_delivery
node_delivery -->|"publishes posts"| node_telegram
node_monitor -->|"checks in background"| node_ai_screen
node_ai_screen -->|"requests verdict"| node_groq_api
node_monitor -->|"handles post lifecycle"| node_lifecycle
node_lifecycle -.->|"uses review state"| node_database
node_admin_panel -->|"manages persisted state"| node_database
node_admin_panel -->|"controls AI screening"| node_monitor
node_admin_panel -->|"tests detection"| node_keywords
node_scheduler -->|"reads summary"| node_database
node_scheduler -->|"sends report"| node_notifier
node_notifier -->|"sends Telegram DM"| node_admin
node_admin_panel -.->|"sends notifications"| node_notifier
node_lifecycle -->|"deletes filled posts"| node_telegram

click node_entry "https://github.com/murodovdev/telegram_job_bot/blob/main/main.py"
click node_clients "https://github.com/murodovdev/telegram_job_bot/blob/main/bot/client.py"
click node_monitor "https://github.com/murodovdev/telegram_job_bot/blob/main/bot/monitor.py"
click node_keywords "https://github.com/murodovdev/telegram_job_bot/blob/main/bot/filters.py"
click node_halal_keywords "https://github.com/murodovdev/telegram_job_bot/blob/main/bot/halal_filter.py"
click node_ai_screen "https://github.com/murodovdev/telegram_job_bot/blob/main/bot/groq_halal.py"
click node_admin_panel "https://github.com/murodovdev/telegram_job_bot/blob/main/bot/admin_bot.py"
click node_scheduler "https://github.com/murodovdev/telegram_job_bot/blob/main/bot/scheduler.py"
click node_notifier "https://github.com/murodovdev/telegram_job_bot/blob/main/bot/notifier.py"
click node_database "https://github.com/murodovdev/telegram_job_bot/blob/main/bot/database.py"
click node_delivery "https://github.com/murodovdev/telegram_job_bot/blob/main/bot/utils.py"
click node_lifecycle "https://github.com/murodovdev/telegram_job_bot/blob/main/bot/monitor.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_entry,node_clients toneBlue
class node_monitor,node_keywords,node_halal_keywords,node_ai_screen,node_lifecycle toneAmber
class node_admin_panel,node_scheduler,node_notifier,node_groq_api toneMint
class node_database,node_delivery toneRose
class node_admin,node_telegram toneIndigo
```

## Components

### Runtime

- [Application startup](https://github.com/murodovdev/telegram_job_bot/blob/main/main.py): `main.py`
- [Dual clients](https://github.com/murodovdev/telegram_job_bot/blob/main/bot/client.py): `bot/client.py`

### Job Processing

- [Event and polling monitor](https://github.com/murodovdev/telegram_job_bot/blob/main/bot/monitor.py): `bot/monitor.py`
- [Job keyword detection](https://github.com/murodovdev/telegram_job_bot/blob/main/bot/filters.py): `bot/filters.py`
- [Halal keyword screening](https://github.com/murodovdev/telegram_job_bot/blob/main/bot/halal_filter.py): `bot/halal_filter.py`
- [AI halal screening](https://github.com/murodovdev/telegram_job_bot/blob/main/bot/groq_halal.py): `bot/groq_halal.py`
- [Post review and group lifecycle](https://github.com/murodovdev/telegram_job_bot/blob/main/bot/monitor.py): `bot/monitor.py`

### Admin Operations

- [Admin control panel](https://github.com/murodovdev/telegram_job_bot/blob/main/bot/admin_bot.py): `bot/admin_bot.py`
- [Daily summary scheduler](https://github.com/murodovdev/telegram_job_bot/blob/main/bot/scheduler.py): `bot/scheduler.py`
- [Admin notifications](https://github.com/murodovdev/telegram_job_bot/blob/main/bot/notifier.py): `bot/notifier.py`

### State and Delivery

- [SQLite state](https://github.com/murodovdev/telegram_job_bot/blob/main/bot/database.py): `bot/database.py`
- [Formatting and rate-limited sending](https://github.com/murodovdev/telegram_job_bot/blob/main/bot/utils.py): `bot/utils.py`

### Other components

- **Administrator**
- **Telegram**
- **Groq API**

## Connections

- Administrator → Admin control panel: manages bot (evidence: `README.md`)
- Telegram → Dual clients: provides updates (evidence: `README.md`)
- Application startup → SQLite state: initializes (evidence: `main.py`)
- Application startup → Event and polling monitor: starts (evidence: `main.py`)
- Application startup → Admin control panel: starts task (evidence: `main.py`)
- Application startup → Daily summary scheduler: starts task (evidence: `main.py`)
- Application startup → Dual clients: keeps connected (evidence: `main.py`)
- Event and polling monitor → Dual clients: registers handlers (evidence: `bot/monitor.py`)
- Dual clients → Telegram: connects accounts (evidence: `bot/client.py`)
- Event and polling monitor → Job keyword detection: checks messages (evidence: `bot/monitor.py`)
- Event and polling monitor → Halal keyword screening: screens jobs (evidence: `bot/monitor.py`)
- Event and polling monitor → SQLite state: checks and records (evidence: `bot/monitor.py`)
- Event and polling monitor → Formatting and rate-limited sending: formats and sends (evidence: `bot/monitor.py`)
- Formatting and rate-limited sending → Telegram: publishes posts (evidence: `README.md`)
- Event and polling monitor → AI halal screening: checks in background (evidence: `README.md`)
- AI halal screening → Groq API: requests verdict (evidence: `bot/groq_halal.py`)
- Event and polling monitor → Post review and group lifecycle: handles post lifecycle (evidence: `README.md`)
- Post review and group lifecycle → SQLite state: uses review state (evidence: `bot/monitor.py`)
- Admin control panel → SQLite state: manages persisted state (evidence: `README.md`)
- Admin control panel → Event and polling monitor: controls AI screening (evidence: `README.md`)
- Admin control panel → Job keyword detection: tests detection (evidence: `bot/admin_bot.py`)
- Daily summary scheduler → SQLite state: reads summary (evidence: `bot/scheduler.py`)
- Daily summary scheduler → Admin notifications: sends report (evidence: `bot/scheduler.py`)
- Admin notifications → Administrator: sends Telegram DM (evidence: `bot/notifier.py`)
- Admin control panel → Admin notifications: sends notifications (evidence: `bot/admin_bot.py`)
- Post review and group lifecycle → Telegram: deletes filled posts (evidence: `README.md`)
