# eeeob/pyroflow architecture

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

- Interactive diagram: https://gitdiagram.com/eeeob/pyroflow
- Repository: https://github.com/eeeob/pyroflow

## Overview

Pyroflow extends Kurigram/Pyrogram with awaitable message and callback waits, while optionally serializing updates that share a key. The main flow is a handler asking through a patched message or client, a listener matching the reply, and the dispatcher intercepting that update before ordinary handlers. Other documented branches provide coordination, filters, keyboards and pagination, and bot-command publication. Relationships involving unsampled implementations are included only where the README or source index supports them; source-level evidence is limited to the excerpts and index shown.

Main entry points: [`pyroflow/update_listener/update_listener.py`](https://github.com/eeeob/pyroflow/blob/main/pyroflow/update_listener/update_listener.py) (Update listeners), [`pyroflow/types/message.py`](https://github.com/eeeob/pyroflow/blob/main/pyroflow/types/message.py) (Message methods), [`pyroflow/dispatcher/dispatcher.py`](https://github.com/eeeob/pyroflow/blob/main/pyroflow/dispatcher/dispatcher.py) (Dispatcher), [`pyroflow/client/client.py`](https://github.com/eeeob/pyroflow/blob/main/pyroflow/client/client.py) (Client API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation waits"]
  node_client["Client API<br/>[client.py]"]
  node_message["Message methods<br/>[message.py]"]
  node_listener["Update listeners<br/>[update_listener.py]"]
  node_typed_listeners["Message and callback listeners"]
  node_keys["Listener keys<br/>[listener_key.py]"]
  node_listener_state["Wait state<br/>[listener_model.py]"]
end

subgraph group_dispatch["Update dispatch"]
  node_dispatcher["Dispatcher<br/>[dispatcher.py]"]
  node_coordinated["Coordinated dispatcher"]
  node_coord_models["Coordination state<br/>[models.py]"]
  node_patching["Pyrogram patching<br/>[patching.py]"]
end

subgraph group_interaction["Bot interaction tools"]
  node_filters["Text and rate filters<br/>[filters.py]"]
  node_callback_data["Callback data<br/>[callback_data.py]"]
  node_layout["Keyboard layout<br/>[layout.py]"]
  node_pagination["Pagination<br/>[pagination.py]"]
end

subgraph group_commands["Bot commands"]
  node_bot_mixin["Bot command mixin"]
  node_bot_command_utils["Command declarations<br/>[bot_commands.py]"]
end

node_developer(("Bot developer"))
node_kurigram["Kurigram runtime"]

node_developer -->|"creates client"| node_client
node_developer -->|"awaits reply"| node_message
node_client -->|"registers listener"| node_listener
node_message -->|"awaits matching update"| node_listener
node_message -->|"derives wait key"| node_keys
node_typed_listeners -->|"specialize"| node_listener
node_listener -->|"files waits by"| node_keys
node_listener -->|"tracks waits"| node_listener_state
node_kurigram -->|"supplies updates"| node_dispatcher
node_dispatcher -->|"offers update first"| node_listener
node_dispatcher -->|"may be replaced by"| node_coordinated
node_coordinated -->|"uses coordination state"| node_coord_models
node_developer -->|"configures filters"| node_filters
node_developer -->|"defines callback data"| node_callback_data
node_callback_data -->|"provides callback filter"| node_filters
node_developer -->|"arranges buttons"| node_layout
node_developer -->|"builds pages"| node_pagination
node_pagination -->|"arranges navigation"| node_layout
node_developer -->|"opts into commands"| node_bot_mixin
node_bot_mixin -->|"collects declarations"| node_bot_command_utils
node_kurigram -->|"classes patched in place"| node_patching

click node_client "https://github.com/eeeob/pyroflow/blob/main/pyroflow/client/client.py"
click node_message "https://github.com/eeeob/pyroflow/blob/main/pyroflow/types/message.py"
click node_listener "https://github.com/eeeob/pyroflow/blob/main/pyroflow/update_listener/update_listener.py"
click node_typed_listeners "https://github.com/eeeob/pyroflow/tree/main/pyroflow/update_listener"
click node_keys "https://github.com/eeeob/pyroflow/blob/main/pyroflow/models/listener_key.py"
click node_listener_state "https://github.com/eeeob/pyroflow/blob/main/pyroflow/models/listener_model.py"
click node_dispatcher "https://github.com/eeeob/pyroflow/blob/main/pyroflow/dispatcher/dispatcher.py"
click node_coordinated "https://github.com/eeeob/pyroflow/blob/main/pyroflow/dispatcher/coordinated_dispatcher/coordinated_dispatcher.py"
click node_coord_models "https://github.com/eeeob/pyroflow/blob/main/pyroflow/dispatcher/coordinated_dispatcher/models.py"
click node_filters "https://github.com/eeeob/pyroflow/blob/main/pyroflow/filters.py"
click node_callback_data "https://github.com/eeeob/pyroflow/blob/main/pyroflow/keyboards/callback_data.py"
click node_layout "https://github.com/eeeob/pyroflow/blob/main/pyroflow/keyboards/layout.py"
click node_pagination "https://github.com/eeeob/pyroflow/blob/main/pyroflow/keyboards/pagination.py"
click node_bot_mixin "https://github.com/eeeob/pyroflow/blob/main/pyroflow/client/bot_commands_mixin.py"
click node_bot_command_utils "https://github.com/eeeob/pyroflow/blob/main/pyroflow/utils/bot_commands.py"
click node_patching "https://github.com/eeeob/pyroflow/blob/main/pyroflow/utils/patching.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_client,node_message,node_listener,node_typed_listeners,node_keys,node_listener_state toneBlue
class node_dispatcher,node_coordinated,node_coord_models,node_patching toneAmber
class node_filters,node_callback_data,node_layout,node_pagination toneMint
class node_bot_mixin,node_bot_command_utils toneRose
class node_developer,node_kurigram toneIndigo
```

## Components

### Conversation waits

- [Client API](https://github.com/eeeob/pyroflow/blob/main/pyroflow/client/client.py): `pyroflow/client/client.py`
- [Message methods](https://github.com/eeeob/pyroflow/blob/main/pyroflow/types/message.py): `pyroflow/types/message.py`
- [Update listeners](https://github.com/eeeob/pyroflow/blob/main/pyroflow/update_listener/update_listener.py): `pyroflow/update_listener/update_listener.py`
- [Message and callback listeners](https://github.com/eeeob/pyroflow/tree/main/pyroflow/update_listener): `pyroflow/update_listener`
- [Listener keys](https://github.com/eeeob/pyroflow/blob/main/pyroflow/models/listener_key.py): `pyroflow/models/listener_key.py`
- [Wait state](https://github.com/eeeob/pyroflow/blob/main/pyroflow/models/listener_model.py): `pyroflow/models/listener_model.py`

### Update dispatch

- [Dispatcher](https://github.com/eeeob/pyroflow/blob/main/pyroflow/dispatcher/dispatcher.py): `pyroflow/dispatcher/dispatcher.py`
- [Coordinated dispatcher](https://github.com/eeeob/pyroflow/blob/main/pyroflow/dispatcher/coordinated_dispatcher/coordinated_dispatcher.py): `pyroflow/dispatcher/coordinated_dispatcher/coordinated_dispatcher.py`
- [Coordination state](https://github.com/eeeob/pyroflow/blob/main/pyroflow/dispatcher/coordinated_dispatcher/models.py): `pyroflow/dispatcher/coordinated_dispatcher/models.py`
- [Pyrogram patching](https://github.com/eeeob/pyroflow/blob/main/pyroflow/utils/patching.py): `pyroflow/utils/patching.py`

### Bot interaction tools

- [Text and rate filters](https://github.com/eeeob/pyroflow/blob/main/pyroflow/filters.py): `pyroflow/filters.py`
- [Callback data](https://github.com/eeeob/pyroflow/blob/main/pyroflow/keyboards/callback_data.py): `pyroflow/keyboards/callback_data.py`
- [Keyboard layout](https://github.com/eeeob/pyroflow/blob/main/pyroflow/keyboards/layout.py): `pyroflow/keyboards/layout.py`
- [Pagination](https://github.com/eeeob/pyroflow/blob/main/pyroflow/keyboards/pagination.py): `pyroflow/keyboards/pagination.py`

### Bot commands

- [Bot command mixin](https://github.com/eeeob/pyroflow/blob/main/pyroflow/client/bot_commands_mixin.py): `pyroflow/client/bot_commands_mixin.py`
- [Command declarations](https://github.com/eeeob/pyroflow/blob/main/pyroflow/utils/bot_commands.py): `pyroflow/utils/bot_commands.py`

### Other components

- **Bot developer**
- **Kurigram runtime**

## Connections

- Bot developer → Client API: creates client (evidence: `README.md`)
- Bot developer → Message methods: awaits reply (evidence: `README.md`)
- Client API → Update listeners: registers listener (evidence: `pyroflow/client/client.py`)
- Message methods → Update listeners: awaits matching update (evidence: `pyroflow/types/message.py`)
- Message methods → Listener keys: derives wait key (evidence: `pyroflow/types/message.py`)
- Message and callback listeners → Update listeners: specialize (evidence: `pyroflow/update_listener/__init__.py`)
- Update listeners → Listener keys: files waits by (evidence: `pyroflow/update_listener/update_listener.py`)
- Update listeners → Wait state: tracks waits (evidence: `pyroflow/models/listener_model.py`)
- Kurigram runtime → Dispatcher: supplies updates (evidence: `README.md`)
- Dispatcher → Update listeners: offers update first (evidence: `pyroflow/dispatcher/dispatcher.py`)
- Dispatcher → Coordinated dispatcher: may be replaced by (evidence: `README.md`)
- Coordinated dispatcher → Coordination state: uses coordination state (evidence: `pyroflow/dispatcher/coordinated_dispatcher/coordinated_dispatcher.py`)
- Bot developer → Text and rate filters: configures filters (evidence: `README.md`)
- Bot developer → Callback data: defines callback data (evidence: `README.md`)
- Callback data → Text and rate filters: provides callback filter (evidence: `pyroflow/keyboards/callback_data.py`)
- Bot developer → Keyboard layout: arranges buttons (evidence: `README.md`)
- Bot developer → Pagination: builds pages (evidence: `README.md`)
- Pagination → Keyboard layout: arranges navigation (evidence: `pyroflow/keyboards/pagination.py`)
- Bot developer → Bot command mixin: opts into commands (evidence: `README.md`)
- Bot command mixin → Command declarations: collects declarations (evidence: `pyroflow/client/bot_commands_mixin.py`)
- Kurigram runtime → Pyrogram patching: classes patched in place (evidence: `README.md`)
