# cnsunyour/tg-guard-bot architecture

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

- Interactive diagram: https://gitdiagram.com/cnsunyour/tg-guard-bot
- Repository: https://github.com/cnsunyour/tg-guard-bot

## Overview

Telegram Guard Bot is a group-moderation bot: Telegram updates enter the application, where join verification and message screening lead to access decisions, moderation actions, or administrator review. Its documented capabilities also include group-management commands, reporting and voting, activity and curfew controls, localization, and large-group cleanup. The graph separates those product stages from detection, persistence, and integrations. Several links reflect README-level capability descriptions; unsampled implementations are represented only at paths supported by the tree, and their internal call relationships are not inferred.

Main entry points: [`src/main.py`](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/main.py) (Update runtime), [`src/bot/handlers/antispam.py`](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/antispam.py) (Message screening), [`src/services/spam_detector.py`](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/services/spam_detector.py) (Spam detection), [`src/bot/handlers/verification.py`](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/verification.py) (Join verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Bot entry"]
  node_app["Update runtime<br/>[main.py]"]
end

subgraph group_safety["Verification and safety"]
  node_verification["Join verification<br/>[verification.py]"]
  node_verification_render["Challenge rendering"]
  node_webapp["CAPTCHA WebApp<br/>[verify.js]"]
  node_altcha["ALTCHA service<br/>[verify.php]"]
  node_cas["CAS screening<br/>[cas_service.py]"]
  node_account_status["Account status"]
end

subgraph group_moderation["Detection and moderation"]
  node_antispam_handler["Message screening<br/>[antispam.py]"]
  node_detector["Spam detection<br/>[spam_detector.py]"]
  node_rules["Rule engine<br/>[rule_engine.py]"]
  node_classifier["ML classifier<br/>[classifier.py]"]
  node_embeddings["Semantic embeddings<br/>[embedder.py]"]
  node_ai_detection["AI detection<br/>[ai_detector.py]"]
  node_context["Conversation context<br/>[context_service.py]"]
  node_review["Spam review<br/>[spam_review.py]"]
  node_moderation_service["Enforcement actions<br/>[moderation.py]"]
  node_reporting["Reports and votes<br/>[moderation.py]"]
end

subgraph group_operations["Group operations"]
  node_group_admin["Group commands<br/>[admin.py]"]
  node_cleanup["Member cleanup<br/>[cleanup.py]"]
  node_curfew["Curfew controls<br/>[curfew.py]"]
  node_activity["Activity scoring<br/>[activity.py]"]
end

subgraph group_infrastructure["Runtime services"]
  node_localization["Localization<br/>[translator.py]"]
  node_groups_repo["Group settings<br/>[group_repo.py]"]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_redis[("Redis state<br/>[redis.py]")]
  node_telethon["Telethon client<br/>[telethon_client.py]"]
end

node_telegram(("Telegram users"))

node_telegram -->|"sends updates"| node_app
node_app -.->|"routes joins"| node_verification
node_app -->|"routes messages"| node_antispam_handler
node_app -->|"routes commands"| node_group_admin
node_verification -->|"renders challenges"| node_verification_render
node_verification -.->|"uses CAPTCHA"| node_webapp
node_webapp -.->|"verifies ALTCHA"| node_altcha
node_verification -->|"checks entrants"| node_cas
node_verification -->|"checks accounts"| node_account_status
node_antispam_handler -->|"screens messages"| node_detector
node_antispam_handler -->|"enforces outcomes"| node_moderation_service
node_antispam_handler -->|"opens review"| node_review
node_detector -.->|"uses rules"| node_rules
node_detector -.->|"uses classifier"| node_classifier
node_detector -.->|"uses embeddings"| node_embeddings
node_detector -.->|"uses AI"| node_ai_detection
node_detector -.->|"uses context"| node_context
node_reporting -->|"applies penalties"| node_moderation_service
node_group_admin -->|"updates settings"| node_groups_repo
node_cleanup -->|"queries members"| node_telethon
node_cleanup -->|"uses client"| node_telethon
node_curfew -->|"updates curfew"| node_groups_repo
node_antispam_handler -->|"reads settings"| node_groups_repo
node_groups_repo -->|"queries groups"| node_database
node_cas -->|"caches results"| node_redis
node_account_status -->|"caches results"| node_redis
node_app -->|"initializes languages"| node_localization
node_app -->|"initializes database"| node_database
node_app -->|"starts client"| node_telethon
node_antispam_handler -->|"records activity"| node_activity
node_curfew -.->|"uses activity"| node_activity

click node_app "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/main.py"
click node_verification "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/verification.py"
click node_verification_render "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/verification_render.py"
click node_webapp "https://github.com/cnsunyour/tg-guard-bot/blob/main/captcha-webapp/functions/api/verify.js"
click node_altcha "https://github.com/cnsunyour/tg-guard-bot/blob/main/altcha-backend/verify.php"
click node_antispam_handler "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/antispam.py"
click node_detector "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/services/spam_detector.py"
click node_rules "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/ml/rule_engine.py"
click node_classifier "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/ml/classifier.py"
click node_embeddings "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/ml/embedder.py"
click node_ai_detection "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/ml/ai_detector.py"
click node_context "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/services/context_service.py"
click node_review "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/services/spam_review.py"
click node_moderation_service "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/services/moderation.py"
click node_reporting "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/moderation.py"
click node_cas "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/services/cas_service.py"
click node_account_status "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/services/user_status_service.py"
click node_group_admin "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/admin.py"
click node_cleanup "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/cleanup.py"
click node_curfew "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/curfew.py"
click node_activity "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/services/activity.py"
click node_localization "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/core/i18n/translator.py"
click node_groups_repo "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/repositories/group_repo.py"
click node_database "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/core/database.py"
click node_redis "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/core/redis.py"
click node_telethon "https://github.com/cnsunyour/tg-guard-bot/blob/main/src/core/telethon_client.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_app,node_telegram toneBlue
class node_verification,node_verification_render,node_webapp,node_altcha,node_cas,node_account_status toneAmber
class node_antispam_handler,node_detector,node_rules,node_classifier,node_embeddings,node_ai_detection,node_context,node_review,node_moderation_service,node_reporting toneMint
class node_group_admin,node_cleanup,node_curfew,node_activity toneRose
class node_localization,node_groups_repo,node_database,node_redis,node_telethon toneIndigo
```

## Components

### Bot entry

- [Update runtime](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/main.py): `src/main.py`

### Verification and safety

- [Join verification](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/verification.py): `src/bot/handlers/verification.py`
- [Challenge rendering](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/verification_render.py): `src/bot/handlers/verification_render.py`
- [CAPTCHA WebApp](https://github.com/cnsunyour/tg-guard-bot/blob/main/captcha-webapp/functions/api/verify.js): `captcha-webapp/functions/api/verify.js`
- [ALTCHA service](https://github.com/cnsunyour/tg-guard-bot/blob/main/altcha-backend/verify.php): `altcha-backend/verify.php`
- [CAS screening](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/services/cas_service.py): `src/services/cas_service.py`
- [Account status](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/services/user_status_service.py): `src/services/user_status_service.py`

### Detection and moderation

- [Message screening](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/antispam.py): `src/bot/handlers/antispam.py`
- [Spam detection](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/services/spam_detector.py): `src/services/spam_detector.py`
- [Rule engine](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/ml/rule_engine.py): `src/ml/rule_engine.py`
- [ML classifier](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/ml/classifier.py): `src/ml/classifier.py`
- [Semantic embeddings](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/ml/embedder.py): `src/ml/embedder.py`
- [AI detection](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/ml/ai_detector.py): `src/ml/ai_detector.py`
- [Conversation context](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/services/context_service.py): `src/services/context_service.py`
- [Spam review](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/services/spam_review.py): `src/services/spam_review.py`
- [Enforcement actions](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/services/moderation.py): `src/services/moderation.py`
- [Reports and votes](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/moderation.py): `src/bot/handlers/moderation.py`

### Group operations

- [Group commands](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/admin.py): `src/bot/handlers/admin.py`
- [Member cleanup](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/cleanup.py): `src/bot/handlers/cleanup.py`
- [Curfew controls](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/bot/handlers/curfew.py): `src/bot/handlers/curfew.py`
- [Activity scoring](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/services/activity.py): `src/services/activity.py`

### Runtime services

- [Localization](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/core/i18n/translator.py): `src/core/i18n/translator.py`
- [Group settings](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/repositories/group_repo.py): `src/repositories/group_repo.py`
- [PostgreSQL](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/core/database.py): `src/core/database.py`
- [Redis state](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/core/redis.py): `src/core/redis.py`
- [Telethon client](https://github.com/cnsunyour/tg-guard-bot/blob/main/src/core/telethon_client.py): `src/core/telethon_client.py`

### Other components

- **Telegram users**

## Connections

- Telegram users → Update runtime: sends updates (evidence: `README.md`)
- Update runtime → Join verification: routes joins (evidence: `src/main.py`)
- Update runtime → Message screening: routes messages (evidence: `src/main.py`)
- Update runtime → Group commands: routes commands (evidence: `src/main.py`)
- Join verification → Challenge rendering: renders challenges (evidence: `src/bot/handlers/verification.py`)
- Join verification → CAPTCHA WebApp: uses CAPTCHA (evidence: `README.md`)
- CAPTCHA WebApp → ALTCHA service: verifies ALTCHA (evidence: `README.md`)
- Join verification → CAS screening: checks entrants (evidence: `src/bot/handlers/verification.py`)
- Join verification → Account status: checks accounts (evidence: `src/bot/handlers/verification.py`)
- Message screening → Spam detection: screens messages (evidence: `src/bot/handlers/antispam.py`)
- Message screening → Enforcement actions: enforces outcomes (evidence: `src/bot/handlers/antispam.py`)
- Message screening → Spam review: opens review (evidence: `src/bot/handlers/antispam.py`)
- Spam detection → Rule engine: uses rules
- Spam detection → ML classifier: uses classifier
- Spam detection → Semantic embeddings: uses embeddings
- Spam detection → AI detection: uses AI
- Spam detection → Conversation context: uses context
- Reports and votes → Enforcement actions: applies penalties (evidence: `src/bot/handlers/moderation.py`)
- Group commands → Group settings: updates settings (evidence: `src/bot/handlers/admin.py`)
- Member cleanup → Telethon client: queries members (evidence: `src/bot/handlers/cleanup.py`)
- Member cleanup → Telethon client: uses client (evidence: `src/bot/handlers/cleanup.py`)
- Curfew controls → Group settings: updates curfew (evidence: `src/bot/handlers/curfew.py`)
- Message screening → Group settings: reads settings (evidence: `src/bot/handlers/antispam.py`)
- Group settings → PostgreSQL: queries groups (evidence: `src/repositories/group_repo.py`)
- CAS screening → Redis state: caches results (evidence: `src/services/cas_service.py`)
- Account status → Redis state: caches results (evidence: `src/services/user_status_service.py`)
- Update runtime → Localization: initializes languages (evidence: `src/main.py`)
- Update runtime → PostgreSQL: initializes database (evidence: `src/main.py`)
- Update runtime → Telethon client: starts client (evidence: `src/main.py`)
- Message screening → Activity scoring: records activity (evidence: `src/bot/handlers/antispam.py`)
- Curfew controls → Activity scoring: uses activity