# rezhajulio/pythonid-bot architecture > Architecture diagram of the GitHub repository rezhajulio/pythonid-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source. - Interactive diagram: https://gitdiagram.com/rezhajulio/pythonid-bot - Repository: https://github.com/rezhajulio/pythonid-bot ## Overview PythonID is a multi-group Telegram moderation bot. It loads shared and per-group settings, registers configurable plugins, then processes group events for profile compliance, new-member verification, spam enforcement and admin moderation; scheduled jobs handle time-based restrictions and recovery. Persistent warning, trust, captcha and probation state is shared through SQLite. The graph preserves documented features whose handler details were not sampled; those links are based on the README or SOURCE INDEX references, not a full inspection of those implementations. Main entry points: [`src/bot/plugins/manager.py`](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/manager.py) (Plugin manager), [`src/bot/database/service.py`](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/database/service.py) (SQLite state), [`src/bot/handlers/captcha.py`](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/captcha.py) (Captcha verification), [`src/bot/main.py`](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/main.py) (Bot runtime) ## Diagram (Mermaid) ```mermaid flowchart TD subgraph group_startup["Startup & Configuration"] node_settings["Bot settings
[config.py]"] node_group_config["Group registry
[group_config.py]"] node_plugin_manager["Plugin manager
[manager.py]"] node_plugin_toggles["Plugin toggles
[config.py]"] node_bot_runtime["Bot runtime
[main.py]"] node_builtin_spam["Spam registrations
[spam.py]"] node_builtin_commands["Command registrations
[commands.py]"] node_builtin_captcha["Captcha registration
[captcha.py]"] node_builtin_profile["Profile registration
[profile_monitor.py]"] node_builtin_ai["AI registration
[ai_monitor.py]"] node_builtin_jobs["Job registration
[jobs.py]"] end subgraph group_moderation["Moderation Workflows"] node_profile_monitor["Profile checks
[message.py]"] node_captcha["Captcha verification
[captcha.py]"] node_spam_enforcement["Spam enforcement
[anti_spam.py]"] node_duplicate_detection["Duplicate spam
[duplicate_spam.py]"] node_bio_bait["Bio-bait detection
[bio_bait.py]"] node_guest_bot["Guest bot blocking
[guest_bot.py]"] node_ai_monitor["AI moderation
[ai_spam_monitor.py]"] end subgraph group_state["State & Shared Services"] node_database[("SQLite state
[service.py]")] node_models["State models
[models.py]"] node_telegram_utils["Telegram utilities
[telegram_utils.py]"] node_restriction_lock["Restriction lock"] node_captcha_recovery["Captcha recovery"] node_scheduler["Restriction scheduler
[scheduler.py]"] node_admin_cache["Admin cache
[admin_cache.py]"] node_classifier_client["Classifier client"] end subgraph group_operations["Admin & Operations"] node_warning_admin["Warnings & trust
[warn.py]"] node_verification_admin["Verify & check
[verify.py]"] node_dm_flow["DM unrestriction
[dm.py]"] node_topic_guard["Topic protection
[topic_guard.py]"] end node_telegram(("Telegram users")) node_telegram_api{{"Telegram API"}} node_classifier{{"classifier.dev"}} node_telegram -->|"sends updates"| node_bot_runtime node_bot_runtime -->|"loads settings"| node_settings node_bot_runtime -->|"initializes groups"| node_group_config node_bot_runtime -->|"registers plugins"| node_plugin_manager node_plugin_manager -->|"registers"| node_builtin_spam node_plugin_manager -->|"registers"| node_builtin_commands node_plugin_manager -->|"registers"| node_builtin_captcha node_plugin_manager -->|"registers"| node_builtin_profile node_plugin_manager -->|"registers"| node_builtin_ai node_plugin_manager -->|"registers"| node_builtin_jobs node_builtin_spam -->|"registers handlers"| node_spam_enforcement node_builtin_spam -->|"registers handler"| node_duplicate_detection node_builtin_spam -->|"registers handler"| node_bio_bait node_builtin_spam -->|"registers handler"| node_guest_bot node_builtin_commands -->|"registers handler"| node_warning_admin node_builtin_commands -->|"registers handlers"| node_verification_admin node_builtin_captcha -->|"registers handler"| node_captcha node_builtin_profile -->|"registers handler"| node_profile_monitor node_builtin_ai -->|"registers handler"| node_ai_monitor node_builtin_jobs -->|"registers jobs"| node_scheduler node_plugin_manager -->|"resolves toggles"| node_plugin_toggles node_bot_runtime -->|"initializes database"| node_database node_profile_monitor -.->|"reads state"| node_database node_captcha -->|"records challenges"| node_database node_captcha -->|"serializes changes"| node_restriction_lock node_captcha -->|"uses helpers"| node_telegram_utils node_spam_enforcement -->|"records violations"| node_database node_spam_enforcement -->|"uses helpers"| node_telegram_utils node_duplicate_detection -->|"reuses checks"| node_spam_enforcement node_guest_bot -->|"reads trust state"| node_database node_guest_bot -->|"serializes changes"| node_restriction_lock node_ai_monitor -->|"requests classification"| node_classifier_client node_classifier_client -->|"calls service"| node_classifier node_ai_monitor -->|"uses helpers"| node_telegram_utils node_captcha_recovery -->|"loads pending challenges"| node_database node_captcha_recovery -->|"recovers challenges"| node_captcha node_scheduler -->|"checks warnings"| node_database node_scheduler -->|"serializes changes"| node_restriction_lock node_admin_cache -->|"lists groups"| node_group_config node_admin_cache -->|"fetches admins"| node_telegram_api node_warning_admin -->|"uses helpers"| node_telegram_utils node_verification_admin -->|"updates whitelist"| node_database node_verification_admin -->|"serializes changes"| node_restriction_lock node_dm_flow -.->|"reads trust state"| node_database node_topic_guard -.->|"protects topic"| node_telegram_api node_spam_enforcement -->|"deletes or restricts"| node_telegram_api node_captcha -->|"challenges members"| node_telegram_api node_telegram_utils -->|"calls Telegram"| node_telegram_api click node_settings "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/config.py" click node_group_config "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/group_config.py" click node_plugin_manager "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/manager.py" click node_plugin_toggles "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/config.py" click node_bot_runtime "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/main.py" click node_profile_monitor "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/message.py" click node_captcha "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/captcha.py" click node_spam_enforcement "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/anti_spam.py" click node_duplicate_detection "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/duplicate_spam.py" click node_bio_bait "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/bio_bait.py" click node_guest_bot "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/guest_bot.py" click node_ai_monitor "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/ai_spam_monitor.py" click node_warning_admin "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/warn.py" click node_verification_admin "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/verify.py" click node_dm_flow "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/dm.py" click node_topic_guard "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/topic_guard.py" click node_database "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/database/service.py" click node_models "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/database/models.py" click node_telegram_utils "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/services/telegram_utils.py" click node_restriction_lock "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/services/restriction_lock.py" click node_captcha_recovery "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/services/captcha_recovery.py" click node_scheduler "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/services/scheduler.py" click node_admin_cache "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/services/admin_cache.py" click node_classifier_client "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/services/classifier_client.py" click node_builtin_spam "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/builtin/spam.py" click node_builtin_commands "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/builtin/commands.py" click node_builtin_captcha "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/builtin/captcha.py" click node_builtin_profile "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/builtin/profile_monitor.py" click node_builtin_ai "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/builtin/ai_monitor.py" click node_builtin_jobs "https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/builtin/jobs.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_settings,node_group_config,node_plugin_manager,node_plugin_toggles,node_bot_runtime,node_builtin_spam,node_builtin_commands,node_builtin_captcha,node_builtin_profile,node_builtin_ai,node_builtin_jobs,node_telegram toneBlue class node_profile_monitor,node_captcha,node_spam_enforcement,node_duplicate_detection,node_bio_bait,node_guest_bot,node_ai_monitor toneAmber class node_database,node_models,node_telegram_utils,node_restriction_lock,node_captcha_recovery,node_scheduler,node_admin_cache,node_classifier_client,node_telegram_api toneMint class node_warning_admin,node_verification_admin,node_dm_flow,node_topic_guard toneRose class node_classifier toneIndigo ``` ## Components ### Startup & Configuration - [Bot settings](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/config.py): `src/bot/config.py` - [Group registry](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/group_config.py): `src/bot/group_config.py` - [Plugin manager](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/manager.py): `src/bot/plugins/manager.py` - [Plugin toggles](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/config.py): `src/bot/plugins/config.py` - [Bot runtime](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/main.py): `src/bot/main.py` - [Spam registrations](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/builtin/spam.py): `src/bot/plugins/builtin/spam.py` - [Command registrations](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/builtin/commands.py): `src/bot/plugins/builtin/commands.py` - [Captcha registration](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/builtin/captcha.py): `src/bot/plugins/builtin/captcha.py` - [Profile registration](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/builtin/profile_monitor.py): `src/bot/plugins/builtin/profile_monitor.py` - [AI registration](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/builtin/ai_monitor.py): `src/bot/plugins/builtin/ai_monitor.py` - [Job registration](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/plugins/builtin/jobs.py): `src/bot/plugins/builtin/jobs.py` ### Moderation Workflows - [Profile checks](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/message.py): `src/bot/handlers/message.py` - [Captcha verification](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/captcha.py): `src/bot/handlers/captcha.py` - [Spam enforcement](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/anti_spam.py): `src/bot/handlers/anti_spam.py` - [Duplicate spam](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/duplicate_spam.py): `src/bot/handlers/duplicate_spam.py` - [Bio-bait detection](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/bio_bait.py): `src/bot/handlers/bio_bait.py` - [Guest bot blocking](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/guest_bot.py): `src/bot/handlers/guest_bot.py` - [AI moderation](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/ai_spam_monitor.py): `src/bot/handlers/ai_spam_monitor.py` ### State & Shared Services - [SQLite state](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/database/service.py): `src/bot/database/service.py` - [State models](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/database/models.py): `src/bot/database/models.py` - [Telegram utilities](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/services/telegram_utils.py): `src/bot/services/telegram_utils.py` - [Restriction lock](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/services/restriction_lock.py): `src/bot/services/restriction_lock.py` - [Captcha recovery](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/services/captcha_recovery.py): `src/bot/services/captcha_recovery.py` - [Restriction scheduler](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/services/scheduler.py): `src/bot/services/scheduler.py` - [Admin cache](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/services/admin_cache.py): `src/bot/services/admin_cache.py` - [Classifier client](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/services/classifier_client.py): `src/bot/services/classifier_client.py` ### Admin & Operations - [Warnings & trust](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/warn.py): `src/bot/handlers/warn.py` - [Verify & check](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/verify.py): `src/bot/handlers/verify.py` - [DM unrestriction](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/dm.py): `src/bot/handlers/dm.py` - [Topic protection](https://github.com/rezhajulio/pythonid-bot/blob/main/src/bot/handlers/topic_guard.py): `src/bot/handlers/topic_guard.py` ### Other components - **Telegram users** - **Telegram API** - **classifier.dev** ## Connections - Telegram users → Bot runtime: sends updates (evidence: `README.md`) - Bot runtime → Bot settings: loads settings (evidence: `src/bot/main.py`) - Bot runtime → Group registry: initializes groups (evidence: `src/bot/main.py`) - Bot runtime → Plugin manager: registers plugins (evidence: `src/bot/main.py`) - Plugin manager → Spam registrations: registers (evidence: `src/bot/plugins/manager.py`) - Plugin manager → Command registrations: registers (evidence: `src/bot/plugins/manager.py`) - Plugin manager → Captcha registration: registers (evidence: `src/bot/plugins/manager.py`) - Plugin manager → Profile registration: registers (evidence: `src/bot/plugins/manager.py`) - Plugin manager → AI registration: registers (evidence: `src/bot/plugins/manager.py`) - Plugin manager → Job registration: registers (evidence: `src/bot/plugins/manager.py`) - Spam registrations → Spam enforcement: registers handlers (evidence: `src/bot/plugins/builtin/spam.py`) - Spam registrations → Duplicate spam: registers handler (evidence: `src/bot/plugins/builtin/spam.py`) - Spam registrations → Bio-bait detection: registers handler (evidence: `src/bot/plugins/builtin/spam.py`) - Spam registrations → Guest bot blocking: registers handler (evidence: `src/bot/plugins/builtin/spam.py`) - Command registrations → Warnings & trust: registers handler (evidence: `src/bot/plugins/builtin/commands.py`) - Command registrations → Verify & check: registers handlers (evidence: `src/bot/plugins/builtin/commands.py`) - Captcha registration → Captcha verification: registers handler (evidence: `src/bot/plugins/builtin/captcha.py`) - Profile registration → Profile checks: registers handler (evidence: `src/bot/plugins/builtin/profile_monitor.py`) - AI registration → AI moderation: registers handler (evidence: `src/bot/plugins/builtin/ai_monitor.py`) - Job registration → Restriction scheduler: registers jobs (evidence: `src/bot/plugins/builtin/jobs.py`) - Plugin manager → Plugin toggles: resolves toggles (evidence: `src/bot/plugins/manager.py`) - Bot runtime → SQLite state: initializes database (evidence: `src/bot/main.py`) - Profile checks → SQLite state: reads state - Captcha verification → SQLite state: records challenges (evidence: `src/bot/handlers/captcha.py`) - Captcha verification → Restriction lock: serializes changes (evidence: `src/bot/handlers/captcha.py`) - Captcha verification → Telegram utilities: uses helpers (evidence: `src/bot/handlers/captcha.py`) - Spam enforcement → SQLite state: records violations (evidence: `src/bot/handlers/anti_spam.py`) - Spam enforcement → Telegram utilities: uses helpers (evidence: `src/bot/handlers/anti_spam.py`) - Duplicate spam → Spam enforcement: reuses checks (evidence: `src/bot/handlers/duplicate_spam.py`) - Guest bot blocking → SQLite state: reads trust state (evidence: `src/bot/handlers/guest_bot.py`) - Guest bot blocking → Restriction lock: serializes changes (evidence: `src/bot/handlers/guest_bot.py`) - AI moderation → Classifier client: requests classification (evidence: `src/bot/handlers/ai_spam_monitor.py`) - Classifier client → classifier.dev: calls service (evidence: `README.md`) - AI moderation → Telegram utilities: uses helpers (evidence: `src/bot/handlers/ai_spam_monitor.py`) - Captcha recovery → SQLite state: loads pending challenges (evidence: `src/bot/services/captcha_recovery.py`) - Captcha recovery → Captcha verification: recovers challenges (evidence: `src/bot/services/captcha_recovery.py`) - Restriction scheduler → SQLite state: checks warnings (evidence: `src/bot/services/scheduler.py`) - Restriction scheduler → Restriction lock: serializes changes (evidence: `src/bot/services/scheduler.py`) - Admin cache → Group registry: lists groups (evidence: `src/bot/services/admin_cache.py`) - Admin cache → Telegram API: fetches admins (evidence: `src/bot/services/admin_cache.py`) - Warnings & trust → Telegram utilities: uses helpers (evidence: `src/bot/handlers/warn.py`) - Verify & check → SQLite state: updates whitelist (evidence: `src/bot/handlers/verify.py`) - Verify & check → Restriction lock: serializes changes (evidence: `src/bot/handlers/verify.py`) - DM unrestriction → SQLite state: reads trust state - Topic protection → Telegram API: protects topic (evidence: `README.md`) - Spam enforcement → Telegram API: deletes or restricts (evidence: `src/bot/handlers/anti_spam.py`) - Captcha verification → Telegram API: challenges members (evidence: `src/bot/handlers/captcha.py`) - Telegram utilities → Telegram API: calls Telegram (evidence: `src/bot/services/telegram_utils.py`)