BotOS-Template

A skeleton of BotOS, a private multi-bot Telegram platform. This repository shows how the project is organised and includes a few small, self-contained pieces of real code. It is not a working bot framework: function bodies are replaced by ..., and there is no database layer, bot logic, configuration or credentials.

What BotOS was for

BotOS was built to run many Telegram bots from one codebase and one database, without writing a new bot application for every idea. It was aimed at student-facing bots (campus utilities, course help, music), and it tried to make the part that is the same in every bot (navigation, permissions, storage, scheduling, logging) a shared platform, so that a new bot is mostly content and a small Python class.

What it was trying to do

• Treat a bot as a small operating system. Each bot is a virtual filesystem of directories and pages stored in the database. Users move through it with shell-like commands (ls, cd, mkdir, cat, ...), and every entry has owners and permissions, so access control works the same way for every bot.
• Keep the user interface in data, not code. Page text, buttons and routing are defined as JSON in the database. Strings in that JSON name Python methods or f-string expressions, which are resolved at runtime against the bot's class, so a bot's UI can change without a redeploy.
• Run many bots as independent workers. Every active bot runs as its own managed async worker, next to job, retry and terminal workers that handle scheduled tasks and retries with shared logging.
• Give bots a common data layer. Three tiers (a generic asyncpg helper, table-specific logic, and thin internal/external database bindings) return a uniform Result object, and models add TTL caching on top.
• Be operable from Telegram itself. Bots could be created from a token, started, put to sleep and edited from chat.

Layout

Path	Role
initializer/	Start-up sequence: loggers, workers
controller/async_workers/	Managed async workers: base class, manager, job scheduler, retry
controller/bot/	Update routers, MainController, method resolver, system pages
controller/directory_manager/	Shell-style commands over the page filesystem
controller/terminal/, controller/threads/	Terminal sessions and the older thread-based workers
db/	Postgres helper, table-level classes, internal/external bindings
model/	Domain models: bots, users, chats, directories/pages/permissions, a music example
utils/	Result, TTL dict/list, time helpers (Gregorian and Jalali), loggers

Pieces that keep their real code: the async worker base class, manager and job scheduler, the TTL dict and list, Result, TimeManager, MethodResolver, keyboard layout, Markdown escaping, the cache decorators and a few plain Postgres helpers.

Running it

python3.12 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python main.py

It imports the package tree and exits with code 0.