Callback and Command Patterns

Prefer small, typed handlers over large router files with implicit state.

Callback queries

Recommended shape:

• typed CallbackData
• @router.callback_query(MyCallback.filter(...))
• await callback.answer(...) for immediate user feedback
• edit_text(...) or edit_reply_markup(...) when the callback updates the current screen
• permission filters close to the router decorator

Commands with reply-aware UX

For command handlers:

• fail fast when args are missing and there is no meaningful reply
• if used as a reply, explicitly merge reply context into the prompt or action
• keep text parsing in helper functions rather than inside business logic
• keep persistence DTO construction outside the handler body when possible

Handler purity

Keep handlers thin:

• parse Telegram input
• call domain or service logic
• render localized output

Move reusable Telegram parsing rules into helpers and DTO-producing functions.