Architecture overview

async def main():
    logging_level = logging.DEBUG if app.arguments.test else logging.INFO
    coloredlogs.install(level=logging_level, milliseconds=True)
    logging.warning("Starting bot...")

    app.owner_id = app.config.settings.owner_id

    # Initialize database connection
    db_url = config.db.database_url
    app.sessionmanager = await db.init(db_url)

    # Configure Telegram Bot API session
    session = AiohttpSession(
        api=TelegramAPIServer.from_base(config.api.bot_api_url))
    token = config.bot.token
    bot_settings = {"session": session}
    app.bot = Bot(token,
                  default=DefaultBotProperties(
                      parse_mode=ParseMode.HTML),
                  **bot_settings)

    storage = MemoryStorage()
    app.dp = Dispatcher(storage=storage)
    app.dp.startup.register(on_startup)
    app.dp.shutdown.register(on_shutdown)

    # Start background services
    from app.vbb.service.checker import check_journeys
    asyncio.create_task(check_journeys())

    from app.utils import add_scheduler_jobs
    await add_scheduler_jobs()

    # Begin polling
    await app.dp.start_polling(app.bot)

app/
├── __main__.py          # Application entry point
├── __init__.py          # Global instances (bot, dp, scheduler)
├── config.py            # Configuration management
├── common.py            # Shared types and utilities
├── db/                  # Database layer
│   ├── base.py         # SQLAlchemy Base
│   ├── models.py       # User, Address, JourneyDB models
│   └── session.py      # Async session management
├── handlers/            # Command and message handlers
│   ├── owner/          # Bot owner commands (ping, stats)
│   └── user/           # User commands (start, help)
├── dialogs/             # aiogram-dialog conversation flows
│   ├── states.py       # FSM state definitions
│   ├── main.py         # Main menu dialog
│   ├── register.py     # User registration flow
│   ├── journeys.py     # Journey search interface
│   ├── settings.py     # User preferences
│   └── addresses.py    # Address management
├── middlewares/         # Request processing middlewares
│   ├── main.py         # Database session injection
│   └── throttling.py   # Rate limiting
├── vbb/                 # VBB API integration
│   ├── func.py         # API wrapper functions
│   ├── models/         # Journey, Leg, Line data models
│   ├── service/        # Background services
│   └── utils.py        # Time conversion helpers
├── utils/               # Utility functions
│   ├── scheduler_jobs.py  # APScheduler job definitions
│   ├── message_builder.py # Message formatting
│   └── address_util.py    # Address string formatting
└── ui/
    └── commands.py      # Bot command menu setup

def get_handlers_router() -> Router:
    from .owner import get_owner_router
    from .user import get_user_router

    router = Router()

    owner_router = get_owner_router()
    user_router = get_user_router()

    router.include_router(owner_router)
    router.include_router(user_router)

    return router

class RegisterSG(StatesGroup):
    MAIN = State()
    HOME_ADDRESS = State()
    DESTINATION_ADDRESS = State()
    FINISH = State()

class JourneysSG(StatesGroup):
    MAIN = State()

class SettingsSG(StatesGroup):
    MAIN = State()
    CHANGE = State()

async def handler(message: Message, f: FMT, **kwargs):
    user = await f.db.get_user(message.from_user.id)
    # Session automatically committed/rolled back

owner_id: int
dp: Dispatcher
sessionmanager: sessionmaker
bot: Bot
config: Config = parse_config("config.toml")
arguments = parse_arguments()
scheduler = AsyncIOScheduler()

from app import bot, dp, sessionmanager, scheduler