src/
├── bot.ts              # createBot() — middleware + handler registration
├── commands/           # /command handlers
├── handlers/           # Message type handlers (text, photo, document)
├── middleware/          # Auth, rate limit, error handling
└── types/context.ts    # BotContext type extension

import type { BotContext } from '../types/context.js'

export async function myCommand(ctx: BotContext): Promise<void> {
  const chatId = ctx.chat?.id
  if (!chatId) return

  const text = (ctx.message && 'text' in ctx.message) ? ctx.message.text ?? '' : ''
  const args = text.replace(/^\/mycommand\s*/, '').trim()

  await ctx.reply('Response', { parse_mode: 'Markdown' })
}

// Specific handlers FIRST
bot.on('callback_query', callbackHandler)
bot.on('photo', photoHandler)
bot.on('document', documentHandler)
// Catch-all LAST
bot.on('text', messageHandler)

const fileLink = await ctx.telegram.getFileLink(fileId)
const response = await fetch(fileLink.href)
const buffer = Buffer.from(await response.arrayBuffer())
await writeFile(tempPath, buffer)

import { Markup } from 'telegraf'

// Button grid
const keyboard = Markup.inlineKeyboard([
  [Markup.button.callback('Option A', 'action:a')],
  [Markup.button.callback('Option B', 'action:b')],
])

await ctx.reply('Choose:', keyboard)

// Handle callback
bot.on('callback_query', async (ctx) => {
  const data = (ctx.callbackQuery as { data?: string }).data
  if (data?.startsWith('action:')) {
    const value = data.split(':')[1]
    await ctx.answerCbQuery()
    await ctx.editMessageText(`Selected: ${value}`)
  }
})

export function myMiddleware() {
  return async (ctx: BotContext, next: () => Promise<void>) => {
    // Before handler
    const start = Date.now()

    await next()

    // After handler
    console.log(`Request took ${Date.now() - start}ms`)
  }
}