# skylord-op/skylord_op architecture

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

- Interactive diagram: https://gitdiagram.com/skylord-op/skylord_op
- Repository: https://github.com/skylord-op/skylord_op

## Overview

1. **Overall shape**
   - This repository is a **Telegram userbot** built on **Telethon**. It is not a web app: the runtime is a long-lived Python process that logs in as a Telegram user account and reacts to messages/events.
   - The architecture is centered around **event-driven plugins** rather than request/response endpoints.

2. **Startup and bootstrap**
   - The entry points are `userbot/__main__.py`, `telesetup.py`, `string_session.py`, and `startup.sh`.
   - Startup is responsible for reading configuration, creating or restoring the Telegram session, initializing the Telethon client, and loading the plugin set.
   - The repo also includes deployment wrappers for **Heroku/Docker** (`Dockerfile`, `Procfile`, `heroku.yml`, `app.json`), so the same bootstrap path is used across local and platform-managed runtimes.

3. **Core runtime boundary**
   - `userbot/_core.py`, `userbot/events.py`, `userbot/utils.py`, and `userbot/uniborgConfig.py` appear to define the shared runtime layer.
   - This layer likely owns:
     - the Telegram client instance,
     - command prefix / event registration,
     - plugin discovery/loading,
     - shared helpers and config access,
     - common exception handling and dispatch behavior.
   - In architecture terms, this is the boundary between the Telethon event stream and the plugin implementations.

4. **Plugin system**
   - The main behavior lives under `userbot/plugins/`.
   - Each file in that directory is a feature module, and the repo has many self-contained plugins covering admin control, moderation, media conversion, search, fun commands, utility commands, and automation.
   - The key architectural point is that each plugin subscribes to Telegram events and performs a narrow task, rather than there being a central business logic service.

5. **Stateful features and persistence**
   - Persistent behavior is separated into `userbot/plugins/sql_helper/`.
   - This is the repository’s state layer for features that need memory across restarts, such as:
     - floods / antiflood,
     - blacklists,
     - filters,
     - mute/gban/gmute/fban state,
     - notes, welcome messages, PM permit, and similar chat policy data.
   - The presence of a SQL helper package indicates **local database-backed state**, not just in-memory command handling.

6. **External service integrations**
   - Several plugins connect to external APIs or services:
     - **Google search/images** (`google.py`, `google2.py`, `google_imgs.py`)
     - **GitHub** actions (`github.py`, `gitcommit.py`, `github_upload.py`)
     - **Telegraph** publishing (`telegraph.py`)
     - **Google Drive / download/upload flows** (`gDrive.py`, `gdrive_download.py`, `gdrivenew.py`)
     - **Translation**, **lyrics**, **weather/climate**, **text-to-speech**, and similar utility APIs.
   - These integrations are all invoked from plugins, so the plugin layer is the outbound I/O edge of the system.

7. **Media and transformation pipeline**
   - A large portion of the plugin set handles media and content transformation:
     - image/video/audio conversion,
     - screenshots, uploads/downloads,
     - text formatting, font generation, figlets, circle/video effects,
     - meme generation and quote rendering.
   - This suggests a pipeline where Telegram media is downloaded, transformed locally using Python tooling and system binaries, then uploaded back to Telegram or external hosts.

8. **Moderation and chat governance**
   - Another major subsystem is group administration and policy enforcement:
     - admin tools, bans/mutes, locks, spam control, pm-permit, antiflood, blacklist, filters, greetings, pinning, and logging.
   - These features rely on both real-time event interception and persistent rules/state from the SQL helper layer.
   - Architecturally, this is the “policy engine” part of the bot.

9. **Inline bot / bot-assisted features**
   - `userbot/plugins/_inlinebot.py` and related modules indicate support for inline interaction and bot-style responses in addition to pure user-account commands.
   - This creates a secondary interaction mode: some actions are triggered through Telegram inline flows or bot helpers, but they still feed into the same Telethon-driven plugin architecture.

10. **Configuration and secrets**
   - Configuration is environment-driven, with `var.py`, `heroku_config.py`, and README-mentioned variables such as `APP_ID`, `API_HASH`, and session string handling.
   - This means the deployment model is “configure at runtime, not compile time,” which is important for the architecture diagram: credentials and runtime options are externalized, not hardcoded.

11. **Packaging and deployment**
   - The project is packaged for Python runtime execution via `requirements.txt`, `requirements-startup.txt`, and `runtime.txt`.
   - `aptfile` and the `Dockerfile` imply some plugins depend on system packages in addition to Python libraries.
   - Operationally, the system is designed to run as a single always-on worker process rather than a horizontally scaled service.

12. **What to show in a diagram**
   - A good architecture diagram would show:
     - **Telegram network** as the primary input/output boundary,
     - **Telethon user session** as the runtime client,
     - **core/event dispatch** in the middle,
     - **plugins** as the main feature layer,
     - **SQL helper / local persistence** as state storage,
     - **external APIs/services** as side integrations,
     - **deployment/runtime wrapper** around the whole process.
   - The dominant data flow is: Telegram event → core dispatcher → plugin → local state/external service → Telegram response.

Main entry points: [`userbot/plugins/core.py`](https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/core.py) (plugin core), [`userbot/_core.py`](https://github.com/skylord-op/skylord_op/blob/master/userbot/_core.py) (core), [`telesetup.py`](https://github.com/skylord-op/skylord_op/blob/master/telesetup.py) (telesetup), [`userbot/plugins/pmpermit.py`](https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/pmpermit.py) (policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & bootstrap"]
  node_startup_sh["startup.sh<br/>shell bootstrap<br/>[startup.sh]"]
  node_main_entry["__main__<br/>python entry<br/>[__main__.py]"]
  node_tele_setup["telesetup<br/>session setup<br/>[telesetup.py]"]
  node_string_sess["session string<br/>session helper<br/>[string_session.py]"]
end

subgraph group_core["Core layer"]
  node_core_rt["core<br/>event runtime<br/>[_core.py]"]
  node_events_mod["events<br/>event defs<br/>[events.py]"]
  node_utils_mod["utils<br/>helpers<br/>[utils.py]"]
  node_config_mod["config<br/>[uniborgConfig.py]"]
end

subgraph group_plugins["Plugins"]
  node_plugin_core["plugin core<br/>plugin loader<br/>[core.py]"]
  node_admin_plug["admin<br/>moderation plugin<br/>[admin.py]"]
  node_policy_plug["policy<br/>moderation plugin<br/>[pmpermit.py]"]
  node_media_plug["media<br/>transformation plugin<br/>[ff_mpeg.py]"]
  node_meme_plug["memes<br/>content plugin<br/>[meme.py]"]
  node_search_plug["search<br/>api plugin<br/>[google.py]"]
  node_inline_plug["inline<br/>bot-assisted<br/>[_inlinebot.py]"]
end

subgraph group_state["Persistence"]
  node_state_plug[("state store<br/>sql-backed policy<br/>[__init__.py]")]
  node_sql_helpers[("sql helpers<br/>sql modules<br/>[blacklist_sql.py]")]
end

subgraph group_integrations["Integrations"]
  node_drive_plug["drive<br/>upload plugin<br/>[gDrive.py]"]
  node_publishing_plug["publish<br/>sharing plugin<br/>[telegraph.py]"]
end

subgraph group_deploy["Deployment"]
  node_deploy_wrap["deploy<br/>platform wrapper"]
end

node_startup_sh -->|"launches"| node_main_entry
node_main_entry -->|"initializes"| node_tele_setup
node_tele_setup -->|"restores"| node_string_sess
node_tele_setup -->|"starts"| node_core_rt
node_core_rt -->|"wires"| node_events_mod
node_core_rt -->|"uses"| node_utils_mod
node_core_rt -->|"reads"| node_config_mod
node_core_rt -->|"loads"| node_plugin_core
node_plugin_core -->|"routes"| node_admin_plug
node_plugin_core -->|"routes"| node_policy_plug
node_plugin_core -->|"routes"| node_media_plug
node_plugin_core -->|"routes"| node_meme_plug
node_plugin_core -->|"routes"| node_search_plug
node_plugin_core -->|"routes"| node_drive_plug
node_plugin_core -->|"routes"| node_publishing_plug
node_plugin_core -->|"routes"| node_inline_plug
node_policy_plug -->|"persists"| node_state_plug
node_policy_plug -->|"stores"| node_sql_helpers
node_admin_plug -->|"updates"| node_state_plug
node_media_plug -->|"transforms"| node_utils_mod
node_media_plug -.->|"relies on"| node_deploy_wrap
node_search_plug -->|"publishes"| node_publishing_plug
node_drive_plug -.->|"integrates"| node_deploy_wrap
node_deploy_wrap -->|"boots"| node_startup_sh

click node_startup_sh "https://github.com/skylord-op/skylord_op/blob/master/startup.sh"
click node_main_entry "https://github.com/skylord-op/skylord_op/blob/master/userbot/__main__.py"
click node_tele_setup "https://github.com/skylord-op/skylord_op/blob/master/telesetup.py"
click node_string_sess "https://github.com/skylord-op/skylord_op/blob/master/string_session.py"
click node_core_rt "https://github.com/skylord-op/skylord_op/blob/master/userbot/_core.py"
click node_events_mod "https://github.com/skylord-op/skylord_op/blob/master/userbot/events.py"
click node_utils_mod "https://github.com/skylord-op/skylord_op/blob/master/userbot/utils.py"
click node_config_mod "https://github.com/skylord-op/skylord_op/blob/master/userbot/uniborgConfig.py"
click node_plugin_core "https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/core.py"
click node_admin_plug "https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/admin.py"
click node_policy_plug "https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/pmpermit.py"
click node_state_plug "https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/sql_helper/__init__.py"
click node_sql_helpers "https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/sql_helper/blacklist_sql.py"
click node_media_plug "https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/ff_mpeg.py"
click node_meme_plug "https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/meme.py"
click node_search_plug "https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/google.py"
click node_drive_plug "https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/gDrive.py"
click node_publishing_plug "https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/telegraph.py"
click node_inline_plug "https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/_inlinebot.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_startup_sh,node_main_entry,node_tele_setup,node_string_sess toneBlue
class node_core_rt,node_events_mod,node_utils_mod,node_config_mod toneAmber
class node_plugin_core,node_admin_plug,node_policy_plug,node_media_plug,node_meme_plug,node_search_plug,node_inline_plug toneMint
class node_state_plug,node_sql_helpers toneRose
class node_drive_plug,node_publishing_plug toneIndigo
class node_deploy_wrap toneTeal
```

## Components

### Runtime & bootstrap

Process entrypoints and session setup

- [startup.sh](https://github.com/skylord-op/skylord_op/blob/master/startup.sh): shell bootstrap · Starts the long-lived bot process · `startup.sh`
- [__main__](https://github.com/skylord-op/skylord_op/blob/master/userbot/__main__.py): python entry · Python entrypoint for the userbot process · `userbot/__main__.py`
- [telesetup](https://github.com/skylord-op/skylord_op/blob/master/telesetup.py): session setup · Creates or restores the Telethon session · `telesetup.py`
- [session string](https://github.com/skylord-op/skylord_op/blob/master/string_session.py): session helper · String-session handling for login/bootstrap · `string_session.py`

### Core layer

Event dispatch, shared helpers, and config

- [core](https://github.com/skylord-op/skylord_op/blob/master/userbot/_core.py): event runtime · Central event dispatch and plugin loading boundary · `userbot/_core.py`
- [events](https://github.com/skylord-op/skylord_op/blob/master/userbot/events.py): event defs · Shared event helpers and command wiring · `userbot/events.py`
- [utils](https://github.com/skylord-op/skylord_op/blob/master/userbot/utils.py): helpers · Common runtime utilities used across plugins · `userbot/utils.py`
- [config](https://github.com/skylord-op/skylord_op/blob/master/userbot/uniborgConfig.py): runtime config · Environment-driven settings and secrets · `userbot/uniborgConfig.py`

### Plugins

Feature modules reacting to Telegram events

- [plugin core](https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/core.py): plugin loader · Shared plugin-side glue and initialization · `userbot/plugins/core.py`
- [admin](https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/admin.py): moderation plugin · Group admin commands and controls · `userbot/plugins/admin.py`
- [policy](https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/pmpermit.py): moderation plugin · PM permit, antiflood, spam, blacklist, locks · `userbot/plugins/pmpermit.py`
- [media](https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/ff_mpeg.py): transformation plugin · Download, convert, upload, and media effects · `userbot/plugins/ff_mpeg.py`
- [memes](https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/meme.py): content plugin · Text, meme, quote, font, and formatting tools · `userbot/plugins/meme.py`
- [search](https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/google.py): api plugin · Search and lookup commands using external services · `userbot/plugins/google.py`
- [inline](https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/_inlinebot.py): bot-assisted · Inline interaction and bot-style responses · `userbot/plugins/_inlinebot.py`

### Persistence

SQL-backed bot state and policies

- [state store](https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/sql_helper/__init__.py): sql-backed policy · Persistent chat policy and moderation state · `userbot/plugins/sql_helper/__init__.py`
- [sql helpers](https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/sql_helper/blacklist_sql.py): sql modules · Backing tables and helpers for persistent features · `userbot/plugins/sql_helper/blacklist_sql.py`

### Integrations

External APIs and media/service adapters

- [drive](https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/gDrive.py): upload plugin · Google Drive and file transfer flows · `userbot/plugins/gDrive.py`
- [publish](https://github.com/skylord-op/skylord_op/blob/master/userbot/plugins/telegraph.py): sharing plugin · Telegraph and paste/upload style publishing · `userbot/plugins/telegraph.py`

### Deployment

Container and platform wrappers

- **deploy**: platform wrapper · Container and platform runtime packaging

## Connections

- startup.sh → __main__: launches · Shell bootstrap hands off to the Python entrypoint
- __main__ → telesetup: initializes · Entrypoint prepares the Telegram session and client
- telesetup → session string: restores · Session creation uses string-session handling when needed
- telesetup → core: starts · Client startup enters the core event runtime
- core → events: wires · Core runtime uses shared event and command definitions
- core → utils: uses · Core and plugins share utility helpers
- core → config: reads · Runtime configuration is loaded from environment-backed settings
- core → plugin core: loads · Core discovers and activates plugin modules
- plugin core → admin: routes · Plugin loader exposes major command groups
- plugin core → policy: routes · Policy and moderation commands are event-driven plugins
- plugin core → media: routes · Media processing commands plug into the same event stream
- plugin core → memes: routes · Text and media-generation features register as plugins
- plugin core → search: routes · External lookup commands are implemented as plugins
- plugin core → drive: routes · Drive upload/download workflows are handled in plugins
- plugin core → publish: routes · Publishing integrations hang off the plugin layer
- plugin core → inline: routes · Inline and bot-assisted flows remain part of the same runtime
- policy → state store: persists · Policy features depend on durable chat state
- policy → sql helpers: stores · Moderation and PM-permit data are backed by SQL helpers
- admin → state store: updates · Administrative actions can change persistent bot state
- media → utils: transforms · Media commands reuse shared helper functions
- media → deploy: relies on · Some transformations depend on packaged runtime binaries
- search → publish: publishes · Search results and fetched content may be published outwards
- drive → deploy: integrates · Drive flows often depend on deployment/runtime tooling
- deploy → startup.sh: boots · Platform wrappers execute the same startup path
