# paulsonoflars/tgbot architecture

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

- Interactive diagram: https://gitdiagram.com/paulsonoflars/tgbot
- Repository: https://github.com/paulsonoflars/tgbot

## Overview

Marie is a modular Telegram group-management bot. Users and administrators send commands or messages; the bot dispatches them to moderation, configuration, and group-feature modules, which may consult PostgreSQL and reply or perform Telegram actions. The README documents configurable module loading and capabilities including moderation, notes, user information, filters, and welcomes. The graph preserves those feature areas; source excerpts are incomplete, so links for unsampled features and integrations are documented only where the README supports them.

Main entry points: [`tg_bot/modules/helper_funcs/chat_status.py`](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/helper_funcs/chat_status.py) (Permission checks), [`tg_bot/modules/sql/__init__.py`](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/__init__.py) (SQL session), [`tg_bot/modules/log_channel.py`](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/log_channel.py) (Log channel), [`tg_bot/modules/sql/users_sql.py`](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/users_sql.py) (User and chat data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_entry["Bot startup and help<br/>[__main__.py]"]
  node_config_dispatch["Configuration and dispatcher<br/>[__init__.py]"]
end

subgraph group_moderation["Group moderation"]
  node_admins["Admin controls<br/>[admin.py]"]
  node_bans["Bans<br/>[bans.py]"]
  node_global_bans["Global bans<br/>[global_bans.py]"]
  node_locks["Locks<br/>[locks.py]"]
  node_mutes["Muting<br/>[muting.py]"]
  node_warnings["Warnings<br/>[warns.py]"]
  node_antiflood["Flood control<br/>[antiflood.py]"]
  node_blacklist["Blacklists<br/>[blacklist.py]"]
  node_disable["Command controls<br/>[disable.py]"]
end

subgraph group_features["Group features"]
  node_filters["Custom filters<br/>[cust_filters.py]"]
  node_notes["Saved notes<br/>[notes.py]"]
  node_welcome["Welcome messages<br/>[welcome.py]"]
  node_rules["Group rules<br/>[rules.py]"]
  node_reporting["Message reporting<br/>[reporting.py]"]
  node_rss["RSS feeds<br/>[rss.py]"]
  node_userinfo["User information<br/>[userinfo.py]"]
  node_users["User tracking<br/>[users.py]"]
  node_log_channel["Log channel<br/>[log_channel.py]"]
end

subgraph group_support["Shared services"]
  node_permissions["Permission checks<br/>[chat_status.py]"]
  node_user_extract["User extraction<br/>[extraction.py]"]
  node_message_format["Message formatting<br/>[string_handling.py]"]
  node_command_handlers["Command handlers<br/>[handlers.py]"]
end

subgraph group_storage["Persistence"]
  node_disable_store[("Disabled commands<br/>[disable_sql.py]")]
  node_filter_store[("Filter data")]
  node_notes_store[("Notes data<br/>[notes_sql.py]")]
  node_warns_store[("Warnings data<br/>[warns_sql.py]")]
  node_welcome_store[("Welcome data<br/>[welcome_sql.py]")]
  node_users_store[("User and chat data<br/>[users_sql.py]")]
  node_sql_session[("SQL session<br/>[__init__.py]")]
end

node_telegram_users(("Telegram users"))
node_telegram{{"Telegram platform"}}

node_telegram_users -->|"send commands"| node_telegram
node_telegram -->|"deliver updates"| node_entry
node_entry -->|"configure runtime"| node_config_dispatch
node_entry -->|"load modules"| node_admins
node_entry -->|"reply to users"| node_telegram
node_admins -->|"check rights"| node_permissions
node_bans -->|"check rights"| node_permissions
node_bans -->|"resolve targets"| node_user_extract
node_global_bans -->|"read user data"| node_users_store
node_locks -->|"check rights"| node_permissions
node_locks -->|"read user data"| node_users_store
node_locks -->|"log actions"| node_log_channel
node_mutes -->|"check rights"| node_permissions
node_mutes -->|"log actions"| node_log_channel
node_warnings -->|"check rights"| node_permissions
node_warnings -->|"read and write"| node_warns_store
node_warnings -->|"log actions"| node_log_channel
node_blacklist -->|"use command controls"| node_disable
node_blacklist -->|"check rights"| node_permissions
node_filters -->|"check rights"| node_permissions
node_filters -->|"read and write"| node_filter_store
node_filters -->|"resolve targets"| node_user_extract
node_notes -->|"check rights"| node_permissions
node_notes -->|"read and write"| node_notes_store
node_welcome -->|"read and write"| node_welcome_store
node_welcome -->|"format messages"| node_message_format
node_log_channel -->|"check rights"| node_permissions
node_log_channel -->|"send logs"| node_telegram
node_users -->|"read and write"| node_users_store
node_config_dispatch -->|"install handlers"| node_command_handlers
node_disable -->|"read and write"| node_disable_store
node_disable_store -->|"use session"| node_sql_session
node_filter_store -->|"use session"| node_sql_session
node_notes_store -->|"use session"| node_sql_session
node_warns_store -->|"use session"| node_sql_session
node_welcome_store -->|"use session"| node_sql_session
node_users_store -->|"use session"| node_sql_session
node_antiflood -.->|"moderate messages"| node_telegram
node_global_bans -.->|"enforce bans"| node_telegram
node_notes -.->|"send saved notes"| node_telegram
node_rss -.->|"post feed updates"| node_telegram
node_reporting -.->|"forward reports"| node_telegram
node_userinfo -.->|"consult user data"| node_users_store
node_rules -.->|"show rules"| node_telegram

click node_admins "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/admin.py"
click node_bans "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/bans.py"
click node_global_bans "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/global_bans.py"
click node_locks "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/locks.py"
click node_mutes "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/muting.py"
click node_warnings "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/warns.py"
click node_antiflood "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/antiflood.py"
click node_blacklist "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/blacklist.py"
click node_disable "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/disable.py"
click node_filters "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/cust_filters.py"
click node_notes "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/notes.py"
click node_welcome "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/welcome.py"
click node_rules "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/rules.py"
click node_reporting "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/reporting.py"
click node_rss "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/rss.py"
click node_userinfo "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/userinfo.py"
click node_users "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/users.py"
click node_log_channel "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/log_channel.py"
click node_entry "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/__main__.py"
click node_config_dispatch "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/__init__.py"
click node_permissions "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/helper_funcs/chat_status.py"
click node_user_extract "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/helper_funcs/extraction.py"
click node_message_format "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/helper_funcs/string_handling.py"
click node_command_handlers "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/helper_funcs/handlers.py"
click node_disable_store "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/disable_sql.py"
click node_filter_store "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/cust_filters_sql.py"
click node_notes_store "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/notes_sql.py"
click node_warns_store "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/warns_sql.py"
click node_welcome_store "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/welcome_sql.py"
click node_users_store "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/users_sql.py"
click node_sql_session "https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/__init__.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_config_dispatch,node_telegram_users toneBlue
class node_admins,node_bans,node_global_bans,node_locks,node_mutes,node_warnings,node_antiflood,node_blacklist,node_disable toneAmber
class node_filters,node_notes,node_welcome,node_rules,node_reporting,node_rss,node_userinfo,node_users,node_log_channel toneMint
class node_permissions,node_user_extract,node_message_format,node_command_handlers toneRose
class node_disable_store,node_filter_store,node_notes_store,node_warns_store,node_welcome_store,node_users_store,node_sql_session,node_telegram toneIndigo
```

## Components

### Bot runtime

- [Bot startup and help](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/__main__.py): `tg_bot/__main__.py`
- [Configuration and dispatcher](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/__init__.py): `tg_bot/__init__.py`

### Group moderation

- [Admin controls](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/admin.py): `tg_bot/modules/admin.py`
- [Bans](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/bans.py): `tg_bot/modules/bans.py`
- [Global bans](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/global_bans.py): `tg_bot/modules/global_bans.py`
- [Locks](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/locks.py): `tg_bot/modules/locks.py`
- [Muting](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/muting.py): `tg_bot/modules/muting.py`
- [Warnings](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/warns.py): `tg_bot/modules/warns.py`
- [Flood control](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/antiflood.py): `tg_bot/modules/antiflood.py`
- [Blacklists](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/blacklist.py): `tg_bot/modules/blacklist.py`
- [Command controls](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/disable.py): `tg_bot/modules/disable.py`

### Group features

- [Custom filters](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/cust_filters.py): `tg_bot/modules/cust_filters.py`
- [Saved notes](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/notes.py): `tg_bot/modules/notes.py`
- [Welcome messages](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/welcome.py): `tg_bot/modules/welcome.py`
- [Group rules](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/rules.py): `tg_bot/modules/rules.py`
- [Message reporting](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/reporting.py): `tg_bot/modules/reporting.py`
- [RSS feeds](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/rss.py): `tg_bot/modules/rss.py`
- [User information](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/userinfo.py): `tg_bot/modules/userinfo.py`
- [User tracking](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/users.py): `tg_bot/modules/users.py`
- [Log channel](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/log_channel.py): `tg_bot/modules/log_channel.py`

### Shared services

- [Permission checks](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/helper_funcs/chat_status.py): `tg_bot/modules/helper_funcs/chat_status.py`
- [User extraction](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/helper_funcs/extraction.py): `tg_bot/modules/helper_funcs/extraction.py`
- [Message formatting](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/helper_funcs/string_handling.py): `tg_bot/modules/helper_funcs/string_handling.py`
- [Command handlers](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/helper_funcs/handlers.py): `tg_bot/modules/helper_funcs/handlers.py`

### Persistence

- [Disabled commands](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/disable_sql.py): `tg_bot/modules/sql/disable_sql.py`
- [Filter data](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/cust_filters_sql.py): `tg_bot/modules/sql/cust_filters_sql.py`
- [Notes data](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/notes_sql.py): `tg_bot/modules/sql/notes_sql.py`
- [Warnings data](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/warns_sql.py): `tg_bot/modules/sql/warns_sql.py`
- [Welcome data](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/welcome_sql.py): `tg_bot/modules/sql/welcome_sql.py`
- [User and chat data](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/users_sql.py): `tg_bot/modules/sql/users_sql.py`
- [SQL session](https://github.com/paulsonoflars/tgbot/blob/master/tg_bot/modules/sql/__init__.py): `tg_bot/modules/sql/__init__.py`

### Other components

- **Telegram users**
- **Telegram platform**

## Connections

- Telegram users → Telegram platform: send commands
- Telegram platform → Bot startup and help: deliver updates (evidence: `tg_bot/__main__.py`)
- Bot startup and help → Configuration and dispatcher: configure runtime (evidence: `tg_bot/__main__.py`)
- Bot startup and help → Admin controls: load modules (evidence: `tg_bot/__main__.py`)
- Bot startup and help → Telegram platform: reply to users (evidence: `tg_bot/__main__.py`)
- Admin controls → Permission checks: check rights (evidence: `tg_bot/modules/admin.py`)
- Bans → Permission checks: check rights (evidence: `tg_bot/modules/bans.py`)
- Bans → User extraction: resolve targets (evidence: `tg_bot/modules/bans.py`)
- Global bans → User and chat data: read user data (evidence: `tg_bot/modules/global_bans.py`)
- Locks → Permission checks: check rights (evidence: `tg_bot/modules/locks.py`)
- Locks → User and chat data: read user data (evidence: `tg_bot/modules/locks.py`)
- Locks → Log channel: log actions (evidence: `tg_bot/modules/locks.py`)
- Muting → Permission checks: check rights (evidence: `tg_bot/modules/muting.py`)
- Muting → Log channel: log actions (evidence: `tg_bot/modules/muting.py`)
- Warnings → Permission checks: check rights (evidence: `tg_bot/modules/warns.py`)
- Warnings → Warnings data: read and write (evidence: `tg_bot/modules/warns.py`)
- Warnings → Log channel: log actions (evidence: `tg_bot/modules/warns.py`)
- Blacklists → Command controls: use command controls (evidence: `tg_bot/modules/blacklist.py`)
- Blacklists → Permission checks: check rights (evidence: `tg_bot/modules/blacklist.py`)
- Custom filters → Permission checks: check rights (evidence: `tg_bot/modules/cust_filters.py`)
- Custom filters → Filter data: read and write (evidence: `tg_bot/modules/cust_filters.py`)
- Custom filters → User extraction: resolve targets (evidence: `tg_bot/modules/cust_filters.py`)
- Saved notes → Permission checks: check rights (evidence: `tg_bot/modules/notes.py`)
- Saved notes → Notes data: read and write (evidence: `tg_bot/modules/notes.py`)
- Welcome messages → Welcome data: read and write (evidence: `tg_bot/modules/welcome.py`)
- Welcome messages → Message formatting: format messages (evidence: `tg_bot/modules/welcome.py`)
- Log channel → Permission checks: check rights (evidence: `tg_bot/modules/log_channel.py`)
- Log channel → Telegram platform: send logs (evidence: `tg_bot/modules/log_channel.py`)
- User tracking → User and chat data: read and write (evidence: `tg_bot/modules/users.py`)
- Configuration and dispatcher → Command handlers: install handlers (evidence: `tg_bot/__init__.py`)
- Command controls → Disabled commands: read and write (evidence: `tg_bot/modules/disable.py`)
- Disabled commands → SQL session: use session (evidence: `tg_bot/modules/sql/__init__.py`)
- Filter data → SQL session: use session (evidence: `tg_bot/modules/sql/__init__.py`)
- Notes data → SQL session: use session (evidence: `tg_bot/modules/sql/__init__.py`)
- Warnings data → SQL session: use session (evidence: `tg_bot/modules/sql/__init__.py`)
- Welcome data → SQL session: use session (evidence: `tg_bot/modules/sql/__init__.py`)
- User and chat data → SQL session: use session (evidence: `tg_bot/modules/sql/users_sql.py`)
- Flood control → Telegram platform: moderate messages
- Global bans → Telegram platform: enforce bans
- Saved notes → Telegram platform: send saved notes
- RSS feeds → Telegram platform: post feed updates
- Message reporting → Telegram platform: forward reports
- User information → User and chat data: consult user data
- Group rules → Telegram platform: show rules
