How I structure a Python Telegram bot so it doesn't become spaghetti

Arppith Andrews — Sun, 18 Oct 2026 09:14:42 +0000

Most Telegram bot tutorials end with the same thing: one giant main.py where handlers, keyboards, and logging are all tangled together. Works for a weekend project. Falls apart the moment you add your fifth command.

Here's the structure I use for every bot now (python-telegram-bot v20):

1. One file per concern. main.py only wires things up. Handlers live in their own module, keyboards in another. Your future self will thank you.

2. The skeleton is always the same:

from telegram import Update
from telegram.ext import Application, CommandHandler

async def start(update: Update, context):
    await update.message.reply_text("Hello! I'm alive.")

def main():
    app = Application.builder().token("YOUR_TOKEN").build()
    app.add_handler(CommandHandler("start", start))
    app.run_polling()

if __name__ == "__main__":
    main()

Everything hangs off this. New command = new handler function + one add_handler line. Nothing else touches anything else.

3. Keyboards are data, not logic. Inline buttons and reply keyboards get their own builder functions that return markup — the handler just calls them. When Telegram changes button behavior (it happens), you fix it in one place.

4. Logging from day one. Not print statements — the logging module, configured once at startup. The first time your bot silently dies at 2am, you'll understand why.

5. Config out of code. Token in an environment variable, never hardcoded. This is the mistake every beginner tutorial teaches.

I got tired of rebuilding this scaffolding for every bot, so I packaged the whole structure — the wired-up main.py, requirements, a setup guide, plus add-on templates for inline buttons, reply keyboards, and logging — into a starter kit: https://shadowatrx.gumroad.com/l/dkyutc

It's the exact skeleton above, ready to run. Grab a token from @botfather, drop it in, and you're live in minutes.

What does your bot structure look like? Always curious how other people organize theirs.

I built a free invoice generator with zero backend

Arppith Andrews — Sun, 18 Oct 2026 09:05:21 +0000

Freelancers lose hours to invoicing admin. I built a free tool that does it in seconds: business/client profiles, line items, tax, discounts, PDF download — all client-side, no signup, no server, no database.

The whole thing is vanilla HTML/CSS/JS on Cloudflare Pages (free tier), with SEO basics baked in: semantic HTML, meta/OG tags, JSON-LD, sitemap. Total hosting cost: $0.

Try it: https://free-invoicegen.pages.dev — feedback welcome, especially from people who invoice for real.

DEV Community: Arppith Andrews

How I structure a Python Telegram bot so it doesn't become spaghetti

I built a free invoice generator with zero backend