# candycrimsie/aiomax2 architecture

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

- Interactive diagram: https://gitdiagram.com/candycrimsie/aiomax2
- Repository: https://github.com/candycrimsie/aiomax2

## Overview

aiomax2 is an asynchronous Python framework for MAX bots. The principal workflow receives updates through Long Polling or Webhook, parses them into typed MAX models, routes events through filters and middleware to application handlers, and lets handlers call Bot methods that communicate with MAX. FSM and keyboard construction are supporting capabilities. The graph uses README and SOURCE INDEX relationships; unsampled implementation details are not inferred beyond those references.

Main entry points: [`src/aiomax2/dispatcher/dispatcher.py`](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/dispatcher/dispatcher.py) (Dispatcher), [`src/aiomax2/dispatcher/event.py`](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/dispatcher/event.py) (Event observers), [`src/aiomax2/bot.py`](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/bot.py) (Bot API methods), [`src/aiomax2/types/message.py`](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/types/message.py) (Message and callback models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Update ingress"]
  node_dispatcher["Dispatcher<br/>[dispatcher.py]"]
  node_webhook["Webhook handler<br/>[handler.py]"]
  node_fastapi["FastAPI adapter<br/>[fastapi.py]"]
end

subgraph group_routing["Event routing"]
  node_router["Router<br/>[router.py]"]
  node_events["Event observers<br/>[event.py]"]
  node_filters["Filters"]
  node_middleware["Middleware<br/>[middleware.py]"]
  node_invoke["Handler invocation<br/>[invoke.py]"]
end

subgraph group_api["MAX API client"]
  node_bot["Bot API methods<br/>[bot.py]"]
  node_transport["HTTP session<br/>[session.py]"]
  node_limiter["Rate limiter<br/>[rate_limiter.py]"]
end

subgraph group_domain["Models and bot features"]
  node_updates["Update models<br/>[update.py]"]
  node_messages["Message and callback models<br/>[message.py]"]
  node_attachments["Attachments and buttons<br/>[attachments.py]"]
  node_users["User and chat models<br/>[user.py]"]
end

subgraph group_state["State and utilities"]
  node_fsm["FSM contexts<br/>[context.py]"]
  node_storage[("Memory storage<br/>[memory.py]")]
  node_keyboard["Keyboard builder<br/>[keyboard.py]"]
end

node_developer(("Bot developer"))
node_max["MAX Bot API"]

node_developer -->|"configures polling"| node_dispatcher
node_developer -->|"mounts webhook"| node_fastapi
node_max -.->|"sends updates"| node_dispatcher
node_max -->|"posts updates"| node_webhook
node_fastapi -->|"adapts requests"| node_webhook
node_webhook -->|"parses payload"| node_updates
node_webhook -->|"feeds update"| node_dispatcher
node_dispatcher -->|"polls updates"| node_bot
node_dispatcher -->|"dispatches events"| node_router
node_router -->|"triggers observers"| node_events
node_router -->|"wraps route"| node_middleware
node_events -->|"evaluates filters"| node_filters
node_events -->|"wraps handlers"| node_middleware
node_events -->|"invokes callbacks"| node_invoke
node_events -->|"checks state"| node_fsm
node_dispatcher -->|"sets up FSM"| node_fsm
node_fsm -->|"persists state"| node_storage
node_bot -->|"sends API requests"| node_transport
node_transport -->|"uses rate limits"| node_limiter
node_bot -->|"calls MAX API"| node_max
node_bot -->|"returns message models"| node_messages
node_messages -->|"message shortcuts"| node_bot
node_updates -->|"contains messages"| node_messages
node_messages -->|"models attachments"| node_attachments
node_messages -->|"models senders"| node_users
node_keyboard -->|"builds markup"| node_attachments

click node_dispatcher "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/dispatcher/dispatcher.py"
click node_webhook "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/webhook/handler.py"
click node_fastapi "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/webhook/fastapi.py"
click node_router "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/dispatcher/router.py"
click node_events "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/dispatcher/event.py"
click node_filters "https://github.com/candycrimsie/aiomax2/tree/main/src/aiomax2/filters"
click node_middleware "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/dispatcher/middleware.py"
click node_invoke "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/dispatcher/invoke.py"
click node_bot "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/bot.py"
click node_transport "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/client/session.py"
click node_limiter "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/client/rate_limiter.py"
click node_updates "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/types/update.py"
click node_messages "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/types/message.py"
click node_attachments "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/types/attachments.py"
click node_users "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/types/user.py"
click node_fsm "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/fsm/context.py"
click node_storage "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/fsm/storage/memory.py"
click node_keyboard "https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/utils/keyboard.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_dispatcher,node_webhook,node_fastapi toneBlue
class node_router,node_events,node_filters,node_middleware,node_invoke toneAmber
class node_bot,node_transport,node_limiter,node_max toneMint
class node_updates,node_messages,node_attachments,node_users toneRose
class node_fsm,node_storage,node_keyboard,node_developer toneIndigo
```

## Components

### Update ingress

- [Dispatcher](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/dispatcher/dispatcher.py): `src/aiomax2/dispatcher/dispatcher.py`
- [Webhook handler](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/webhook/handler.py): `src/aiomax2/webhook/handler.py`
- [FastAPI adapter](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/webhook/fastapi.py): `src/aiomax2/webhook/fastapi.py`

### Event routing

- [Router](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/dispatcher/router.py): `src/aiomax2/dispatcher/router.py`
- [Event observers](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/dispatcher/event.py): `src/aiomax2/dispatcher/event.py`
- [Filters](https://github.com/candycrimsie/aiomax2/tree/main/src/aiomax2/filters): `src/aiomax2/filters`
- [Middleware](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/dispatcher/middleware.py): `src/aiomax2/dispatcher/middleware.py`
- [Handler invocation](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/dispatcher/invoke.py): `src/aiomax2/dispatcher/invoke.py`

### MAX API client

- [Bot API methods](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/bot.py): `src/aiomax2/bot.py`
- [HTTP session](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/client/session.py): `src/aiomax2/client/session.py`
- [Rate limiter](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/client/rate_limiter.py): `src/aiomax2/client/rate_limiter.py`

### Models and bot features

- [Update models](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/types/update.py): `src/aiomax2/types/update.py`
- [Message and callback models](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/types/message.py): `src/aiomax2/types/message.py`
- [Attachments and buttons](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/types/attachments.py): `src/aiomax2/types/attachments.py`
- [User and chat models](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/types/user.py): `src/aiomax2/types/user.py`

### State and utilities

- [FSM contexts](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/fsm/context.py): `src/aiomax2/fsm/context.py`
- [Memory storage](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/fsm/storage/memory.py): `src/aiomax2/fsm/storage/memory.py`
- [Keyboard builder](https://github.com/candycrimsie/aiomax2/blob/main/src/aiomax2/utils/keyboard.py): `src/aiomax2/utils/keyboard.py`

### Other components

- **Bot developer**
- **MAX Bot API**

## Connections

- Bot developer → Dispatcher: configures polling (evidence: `README.md`)
- Bot developer → FastAPI adapter: mounts webhook (evidence: `README.md`)
- MAX Bot API → Dispatcher: sends updates (evidence: `README.md`)
- MAX Bot API → Webhook handler: posts updates (evidence: `README.md`)
- FastAPI adapter → Webhook handler: adapts requests (evidence: `src/aiomax2/webhook/fastapi.py`)
- Webhook handler → Update models: parses payload (evidence: `src/aiomax2/webhook/handler.py`)
- Webhook handler → Dispatcher: feeds update (evidence: `src/aiomax2/webhook/handler.py`)
- Dispatcher → Bot API methods: polls updates (evidence: `src/aiomax2/dispatcher/dispatcher.py`)
- Dispatcher → Router: dispatches events (evidence: `src/aiomax2/dispatcher/dispatcher.py`)
- Router → Event observers: triggers observers (evidence: `src/aiomax2/dispatcher/router.py`)
- Router → Middleware: wraps route (evidence: `src/aiomax2/dispatcher/router.py`)
- Event observers → Filters: evaluates filters (evidence: `src/aiomax2/dispatcher/event.py`)
- Event observers → Middleware: wraps handlers (evidence: `src/aiomax2/dispatcher/event.py`)
- Event observers → Handler invocation: invokes callbacks (evidence: `src/aiomax2/dispatcher/event.py`)
- Event observers → FSM contexts: checks state (evidence: `src/aiomax2/dispatcher/event.py`)
- Dispatcher → FSM contexts: sets up FSM (evidence: `src/aiomax2/dispatcher/dispatcher.py`)
- FSM contexts → Memory storage: persists state (evidence: `src/aiomax2/fsm/context.py`)
- Bot API methods → HTTP session: sends API requests (evidence: `src/aiomax2/bot.py`)
- HTTP session → Rate limiter: uses rate limits (evidence: `src/aiomax2/client/session.py`)
- Bot API methods → MAX Bot API: calls MAX API (evidence: `README.md`)
- Bot API methods → Message and callback models: returns message models (evidence: `src/aiomax2/bot.py`)
- Message and callback models → Bot API methods: message shortcuts (evidence: `src/aiomax2/types/message.py`)
- Update models → Message and callback models: contains messages (evidence: `src/aiomax2/types/update.py`)
- Message and callback models → Attachments and buttons: models attachments (evidence: `src/aiomax2/types/message.py`)
- Message and callback models → User and chat models: models senders (evidence: `src/aiomax2/types/message.py`)
- Keyboard builder → Attachments and buttons: builds markup (evidence: `src/aiomax2/utils/keyboard.py`)
