How skylord-op/skylord_op works
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: core.py plugin core · _core.py core · telesetup.py telesetup · pmpermit.py policy
Components 20
Runtime & bootstrap
Process entrypoints and session setup
- startup.sh · Starts the long-lived bot process
startup.sh - __main__ · Python entrypoint for the userbot process
userbot/__main__.py - telesetup · Creates or restores the Telethon session
telesetup.py - session string · String-session handling for login/bootstrap
string_session.py
Core layer
Event dispatch, shared helpers, and config
Plugins
Feature modules reacting to Telegram events
- plugin core · Shared plugin-side glue and initialization
userbot/plugins/core.py - admin · Group admin commands and controls
userbot/plugins/admin.py - policy · PM permit, antiflood, spam, blacklist, locks
userbot/plugins/pmpermit.py - media · Download, convert, upload, and media effects
userbot/plugins/ff_mpeg.py - memes · Text, meme, quote, font, and formatting tools
userbot/plugins/meme.py - search · Search and lookup commands using external services
userbot/plugins/google.py - inline · Inline interaction and bot-style responses
userbot/plugins/_inlinebot.py
Persistence
SQL-backed bot state and policies
- state store · Persistent chat policy and moderation state
userbot/plugins/sql_helper/__init__.py - sql helpers · Backing tables and helpers for persistent features
userbot/plugins/sql_helper/blacklist_sql.py
Integrations
External APIs and media/service adapters
Deployment
Container and platform wrappers
- deploy · Container and platform runtime packaging
Connections 24
- 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