# chillbroz005/telegram-bot architecture

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

- Interactive diagram: https://gitdiagram.com/chillbroz005/telegram-bot
- Repository: https://github.com/chillbroz005/telegram-bot

## Overview

This is a Telegram group-moderation bot: it checks ordinary text for punctuation and recognized English words, removes messages that fail, and lets authorized users manage allow/deny lists and list managers. The single Python module also loads and saves that state. The excerpts are partial, so the graph shows only supported validation, permission, persistence, and handler relationships.

Main entry points: [`word_filter_bot.py`](https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py) (Polling application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_application["Polling application<br/>[word_filter_bot.py]"]
  node_statefile["JSON state file"]
end

subgraph group_moderation["Message moderation"]
  node_moderate["Message moderation<br/>[word_filter_bot.py]"]
  node_validation["Message validation<br/>[word_filter_bot.py]"]
  node_punctuation["Punctuation check<br/>[word_filter_bot.py]"]
  node_wordcheck["Word and list check<br/>[word_filter_bot.py]"]
  node_normalize["Deobfuscation<br/>[word_filter_bot.py]"]
  node_spellchecker["SpellChecker"]
end

subgraph group_management["List management"]
  node_commands["List commands<br/>[word_filter_bot.py]"]
  node_permissions["Role permissions<br/>[word_filter_bot.py]"]
  node_lists["Lists and roles<br/>[word_filter_bot.py]"]
end

node_members(("Group members"))
node_admins(("Group admins"))
node_telegram["Telegram API"]

node_members -->|"send messages"| node_telegram
node_admins -->|"send commands"| node_telegram
node_telegram -->|"deliver updates"| node_application
node_application -->|"dispatch text"| node_moderate
node_application -->|"dispatch commands"| node_commands
node_moderate -->|"validate text"| node_validation
node_validation -->|"check punctuation"| node_punctuation
node_validation -->|"check words"| node_wordcheck
node_wordcheck -->|"deobfuscate"| node_normalize
node_wordcheck -->|"check spelling"| node_spellchecker
node_moderate -->|"delete and warn"| node_telegram
node_commands -->|"check access"| node_permissions
node_permissions -->|"check roles"| node_lists
node_permissions -->|"get chat member"| node_telegram
node_commands -->|"edit or read"| node_lists
node_commands -->|"save state"| node_statefile
node_application -->|"load state"| node_statefile

click node_application "https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py"
click node_moderate "https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py"
click node_validation "https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py"
click node_punctuation "https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py"
click node_wordcheck "https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py"
click node_normalize "https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py"
click node_commands "https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py"
click node_permissions "https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py"
click node_lists "https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.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_application,node_statefile toneBlue
class node_moderate,node_validation,node_punctuation,node_wordcheck,node_normalize,node_spellchecker toneAmber
class node_commands,node_permissions,node_lists,node_telegram toneMint
class node_members,node_admins toneIndigo
```

## Components

### Bot runtime

- [Polling application](https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py): `word_filter_bot.py`
- **JSON state file**

### Message moderation

- [Message moderation](https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py): `word_filter_bot.py`
- [Message validation](https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py): `word_filter_bot.py`
- [Punctuation check](https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py): `word_filter_bot.py`
- [Word and list check](https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py): `word_filter_bot.py`
- [Deobfuscation](https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py): `word_filter_bot.py`
- **SpellChecker**

### List management

- [List commands](https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py): `word_filter_bot.py`
- [Role permissions](https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py): `word_filter_bot.py`
- [Lists and roles](https://github.com/chillbroz005/telegram-bot/blob/main/word_filter_bot.py): `word_filter_bot.py`

### Other components

- **Group members**
- **Group admins**
- **Telegram API**

## Connections

- Group members → Telegram API: send messages
- Group admins → Telegram API: send commands
- Telegram API → Polling application: deliver updates
- Polling application → Message moderation: dispatch text
- Polling application → List commands: dispatch commands
- Message moderation → Message validation: validate text
- Message validation → Punctuation check: check punctuation
- Message validation → Word and list check: check words
- Word and list check → Deobfuscation: deobfuscate
- Word and list check → SpellChecker: check spelling
- Message moderation → Telegram API: delete and warn
- List commands → Role permissions: check access
- Role permissions → Lists and roles: check roles
- Role permissions → Telegram API: get chat member
- List commands → Lists and roles: edit or read
- List commands → JSON state file: save state
- Polling application → JSON state file: load state