# thelovii/maxo architecture

> Architecture diagram of the GitHub repository thelovii/maxo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thelovii/maxo
- Repository: https://github.com/thelovii/maxo

## Overview

maxo is an asynchronous Python framework and client library for building MAX bots. The main workflow is to receive platform updates through polling or a webhook, dispatch them through routers and filters to application handlers, and use the bot API client to send results. FSM and dialogs add stateful, multi-step interactions; generated API methods and types support the client. The graph includes documented capabilities whose implementations were not sampled; those links cite the README, and source-level evidence is limited to the supplied excerpts and SOURCE INDEX.

Main entry points: [`src/maxo/bot/api_client.py`](https://github.com/thelovii/maxo/blob/master/src/maxo/bot/api_client.py) (API client), [`src/maxo/routing/dispatcher.py`](https://github.com/thelovii/maxo/blob/master/src/maxo/routing/dispatcher.py) (Dispatcher), [`src/maxo/routing/handlers`](https://github.com/thelovii/maxo/tree/master/src/maxo/routing/handlers) (Bot handlers), [`src/maxo/dialogs/manager/manager.py`](https://github.com/thelovii/maxo/blob/master/src/maxo/dialogs/manager/manager.py) (Dialog manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Bot runtime"]
  node_bot["Bot client<br/>[bot.py]"]
  node_api_client["API client<br/>[api_client.py]"]
  node_polling["Long polling<br/>[long_polling.py]"]
  node_webhook["Webhook transport"]
end

subgraph group_routing["Update routing"]
  node_dispatcher["Dispatcher<br/>[dispatcher.py]"]
  node_routers["Routers and filters"]
  node_middleware["Routing middleware"]
  node_handlers["Bot handlers"]
end

subgraph group_interaction["Stateful interactions"]
  node_fsm["FSM state<br/>[state.py]"]
  node_fsm_storage[("FSM storage")]
  node_dialog_manager["Dialog manager<br/>[manager.py]"]
  node_dialog_widgets["Dialog widgets"]
  node_dialog_storage[("Dialog storage<br/>[storage.py]")]
end

subgraph group_platform["MAX API platform"]
  node_api_methods["API methods"]
  node_api_types["API types"]
  node_api_errors["API errors<br/>[api.py]"]
end

subgraph group_generation["API generation"]
  node_profile["MAX API profile<br/>[profile.py]"]
  node_overrides["Generation overrides<br/>[overrides.py]"]
  node_emitter["Code emitter<br/>[emit.py]"]
end

node_developer(("Bot developer"))
node_max_platform(("MAX platform"))

node_developer -->|"configures"| node_bot
node_developer -->|"registers handlers"| node_dispatcher
node_max_platform -->|"sends updates"| node_polling
node_max_platform -->|"sends updates"| node_webhook
node_polling -->|"dispatches updates"| node_dispatcher
node_webhook -->|"dispatches updates"| node_dispatcher
node_dispatcher -->|"routes updates"| node_routers
node_routers -->|"invokes handlers"| node_handlers
node_handlers -->|"calls bot"| node_bot
node_bot -->|"uses client"| node_api_client
node_api_client -->|"uses methods"| node_api_methods
node_api_client -->|"uses types"| node_api_types
node_api_client -->|"raises errors"| node_api_errors
node_api_client -->|"calls API"| node_max_platform
node_dispatcher -.->|"runs middleware"| node_middleware
node_middleware -.->|"provides state"| node_fsm
node_handlers -->|"controls dialogs"| node_dialog_manager
node_dialog_manager -->|"renders windows"| node_dialog_widgets
node_dialog_manager -->|"loads and saves"| node_dialog_storage
node_dialog_storage -->|"uses storage interface"| node_fsm_storage
node_profile -->|"applies rules"| node_overrides
node_emitter -->|"renders profile"| node_profile

click node_bot "https://github.com/thelovii/maxo/blob/master/src/maxo/bot/bot.py"
click node_api_client "https://github.com/thelovii/maxo/blob/master/src/maxo/bot/api_client.py"
click node_polling "https://github.com/thelovii/maxo/blob/master/src/maxo/transport/long_polling.py"
click node_webhook "https://github.com/thelovii/maxo/tree/master/src/maxo/transport/webhook"
click node_dispatcher "https://github.com/thelovii/maxo/blob/master/src/maxo/routing/dispatcher.py"
click node_routers "https://github.com/thelovii/maxo/tree/master/src/maxo/routing/routers"
click node_middleware "https://github.com/thelovii/maxo/tree/master/src/maxo/routing/middlewares"
click node_handlers "https://github.com/thelovii/maxo/tree/master/src/maxo/routing/handlers"
click node_fsm "https://github.com/thelovii/maxo/blob/master/src/maxo/fsm/state.py"
click node_fsm_storage "https://github.com/thelovii/maxo/tree/master/src/maxo/fsm/storages"
click node_dialog_manager "https://github.com/thelovii/maxo/blob/master/src/maxo/dialogs/manager/manager.py"
click node_dialog_widgets "https://github.com/thelovii/maxo/tree/master/src/maxo/dialogs/widgets"
click node_dialog_storage "https://github.com/thelovii/maxo/blob/master/src/maxo/dialogs/context/storage.py"
click node_api_methods "https://github.com/thelovii/maxo/tree/master/src/maxo/bot/methods"
click node_api_types "https://github.com/thelovii/maxo/tree/master/src/maxo/types"
click node_api_errors "https://github.com/thelovii/maxo/blob/master/src/maxo/errors/api.py"
click node_profile "https://github.com/thelovii/maxo/blob/master/butcher/profile.py"
click node_overrides "https://github.com/thelovii/maxo/blob/master/butcher/overrides.py"
click node_emitter "https://github.com/thelovii/maxo/blob/master/butcher/emit.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bot,node_api_client,node_polling,node_webhook toneBlue
class node_dispatcher,node_routers,node_middleware,node_handlers toneAmber
class node_fsm,node_fsm_storage,node_dialog_manager,node_dialog_widgets,node_dialog_storage toneMint
class node_api_methods,node_api_types,node_api_errors toneRose
class node_profile,node_overrides,node_emitter,node_developer,node_max_platform toneIndigo
```

## Components

### Bot runtime

- [Bot client](https://github.com/thelovii/maxo/blob/master/src/maxo/bot/bot.py): `src/maxo/bot/bot.py`
- [API client](https://github.com/thelovii/maxo/blob/master/src/maxo/bot/api_client.py): `src/maxo/bot/api_client.py`
- [Long polling](https://github.com/thelovii/maxo/blob/master/src/maxo/transport/long_polling.py): `src/maxo/transport/long_polling.py`
- [Webhook transport](https://github.com/thelovii/maxo/tree/master/src/maxo/transport/webhook): `src/maxo/transport/webhook`

### Update routing

- [Dispatcher](https://github.com/thelovii/maxo/blob/master/src/maxo/routing/dispatcher.py): `src/maxo/routing/dispatcher.py`
- [Routers and filters](https://github.com/thelovii/maxo/tree/master/src/maxo/routing/routers): `src/maxo/routing/routers`
- [Routing middleware](https://github.com/thelovii/maxo/tree/master/src/maxo/routing/middlewares): `src/maxo/routing/middlewares`
- [Bot handlers](https://github.com/thelovii/maxo/tree/master/src/maxo/routing/handlers): `src/maxo/routing/handlers`

### Stateful interactions

- [FSM state](https://github.com/thelovii/maxo/blob/master/src/maxo/fsm/state.py): `src/maxo/fsm/state.py`
- [FSM storage](https://github.com/thelovii/maxo/tree/master/src/maxo/fsm/storages): `src/maxo/fsm/storages`
- [Dialog manager](https://github.com/thelovii/maxo/blob/master/src/maxo/dialogs/manager/manager.py): `src/maxo/dialogs/manager/manager.py`
- [Dialog widgets](https://github.com/thelovii/maxo/tree/master/src/maxo/dialogs/widgets): `src/maxo/dialogs/widgets`
- [Dialog storage](https://github.com/thelovii/maxo/blob/master/src/maxo/dialogs/context/storage.py): `src/maxo/dialogs/context/storage.py`

### MAX API platform

- [API methods](https://github.com/thelovii/maxo/tree/master/src/maxo/bot/methods): `src/maxo/bot/methods`
- [API types](https://github.com/thelovii/maxo/tree/master/src/maxo/types): `src/maxo/types`
- [API errors](https://github.com/thelovii/maxo/blob/master/src/maxo/errors/api.py): `src/maxo/errors/api.py`

### API generation

- [MAX API profile](https://github.com/thelovii/maxo/blob/master/butcher/profile.py): `butcher/profile.py`
- [Generation overrides](https://github.com/thelovii/maxo/blob/master/butcher/overrides.py): `butcher/overrides.py`
- [Code emitter](https://github.com/thelovii/maxo/blob/master/butcher/emit.py): `butcher/emit.py`

### Other components

- **Bot developer**
- **MAX platform**

## Connections

- Bot developer → Bot client: configures (evidence: `README.md`)
- Bot developer → Dispatcher: registers handlers (evidence: `README.md`)
- MAX platform → Long polling: sends updates (evidence: `README.md`)
- MAX platform → Webhook transport: sends updates (evidence: `README.md`)
- Long polling → Dispatcher: dispatches updates (evidence: `README.md`)
- Webhook transport → Dispatcher: dispatches updates (evidence: `README.md`)
- Dispatcher → Routers and filters: routes updates (evidence: `README.md`)
- Routers and filters → Bot handlers: invokes handlers (evidence: `README.md`)
- Bot handlers → Bot client: calls bot (evidence: `README.md`)
- Bot client → API client: uses client (evidence: `src/maxo/bot/api_client.py`)
- API client → API methods: uses methods (evidence: `src/maxo/bot/api_client.py`)
- API client → API types: uses types (evidence: `src/maxo/bot/api_client.py`)
- API client → API errors: raises errors (evidence: `src/maxo/bot/api_client.py`)
- API client → MAX platform: calls API (evidence: `README.md`)
- Dispatcher → Routing middleware: runs middleware
- Routing middleware → FSM state: provides state
- Bot handlers → Dialog manager: controls dialogs (evidence: `README.md`)
- Dialog manager → Dialog widgets: renders windows (evidence: `README.md`)
- Dialog manager → Dialog storage: loads and saves (evidence: `src/maxo/dialogs/manager/manager.py`)
- Dialog storage → FSM storage: uses storage interface (evidence: `src/maxo/dialogs/context/storage.py`)
- MAX API profile → Generation overrides: applies rules (evidence: `butcher/profile.py`)
- Code emitter → MAX API profile: renders profile (evidence: `butcher/emit.py`)
