# miraliog/pelegram architecture

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

- Interactive diagram: https://gitdiagram.com/miraliog/pelegram
- Repository: https://github.com/miraliog/pelegram

## Overview

Pelegram is a webhook-only PHP wrapper for the Telegram Bot API. Its principal workflow is Telegram delivering an update to the application, Update exposing typed accessors and type detection, Router matching and dispatching it to a registered handler, and the handler using Bot or typed message/query actions to reply through Telegram. Filters, middleware, per-user state, typed objects, enums, and fluent keyboard builders support that workflow. The excerpts show Bot API calls and routing, but not all Router dispatch paths or Bot internals; unsupported connections are omitted.

Main entry points: [`src/Router.php`](https://github.com/miraliog/pelegram/blob/main/src/Router.php) (Router), [`src/Bot.php`](https://github.com/miraliog/pelegram/blob/main/src/Bot.php) (Bot API client), [`src/Types/Message.php`](https://github.com/miraliog/pelegram/blob/main/src/Types/Message.php) (Message), [`src/Update.php`](https://github.com/miraliog/pelegram/blob/main/src/Update.php) (Webhook update)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_updates["Updates and types"]
  node_update["Webhook update<br/>[Update.php]"]
  node_accessors["Update accessors"]
  node_detect["Update detection"]
  node_message["Message<br/>[Message.php]"]
  node_callback["Callback query<br/>[CallbackQuery.php]"]
  node_inline["Inline query<br/>[InlineQuery.php]"]
end

subgraph group_routing["Routing and state"]
  node_router["Router<br/>[Router.php]"]
  node_entry["Handler entry<br/>[HandlerEntry.php]"]
  node_filters["Filters"]
  node_middleware["Middleware"]
  node_state["User state<br/>[State.php]"]
  node_state_data["State data<br/>[StateData.php]"]
  node_state_drivers["State drivers"]
end

subgraph group_api["Telegram API"]
  node_bot["Bot API client<br/>[Bot.php]"]
  node_enums["API enums"]
end

subgraph group_markup["Keyboards"]
  node_reply_keyboard["Reply keyboards"]
  node_inline_keyboard["Inline keyboards"]
  node_keyboard_buttons["Keyboard buttons<br/>[KeyboardButton.php]"]
  node_inline_buttons["Inline buttons"]
  node_remove_keyboard["Keyboard removal"]
end

node_telegram(("Telegram"))
node_app(("Bot application"))

node_telegram -->|"delivers webhook"| node_update
node_app -->|"dispatches bot"| node_router
node_router -->|"routes update"| node_update
node_update -->|"uses traits"| node_accessors
node_update -->|"uses traits"| node_detect
node_router -->|"registers handlers"| node_entry
node_entry -->|"checks filters"| node_filters
node_router -->|"applies filters"| node_filters
node_router -->|"runs middleware"| node_middleware
node_router -->|"constructs message"| node_message
node_router -->|"constructs query"| node_callback
node_router -->|"constructs query"| node_inline
node_router -->|"loads state"| node_state
node_state -->|"provides data"| node_state_data
node_state -->|"uses driver"| node_state_drivers
node_message -->|"calls API"| node_bot
node_callback -->|"calls API"| node_bot
node_inline -->|"calls API"| node_bot
node_bot -->|"sends API requests"| node_telegram
node_reply_keyboard -->|"contains buttons"| node_keyboard_buttons
node_inline_keyboard -->|"contains buttons"| node_inline_buttons
node_message -->|"accepts markup"| node_reply_keyboard
node_message -->|"accepts markup"| node_inline_keyboard
node_message -->|"accepts markup"| node_remove_keyboard
node_bot -->|"serializes markup"| node_reply_keyboard
node_bot -->|"serializes markup"| node_inline_keyboard
node_bot -->|"serializes markup"| node_remove_keyboard

click node_update "https://github.com/miraliog/pelegram/blob/main/src/Update.php"
click node_accessors "https://github.com/miraliog/pelegram/tree/main/src/Concerns/Accessors"
click node_detect "https://github.com/miraliog/pelegram/tree/main/src/Concerns/Update"
click node_message "https://github.com/miraliog/pelegram/blob/main/src/Types/Message.php"
click node_callback "https://github.com/miraliog/pelegram/blob/main/src/Types/CallbackQuery.php"
click node_inline "https://github.com/miraliog/pelegram/blob/main/src/Types/InlineQuery.php"
click node_router "https://github.com/miraliog/pelegram/blob/main/src/Router.php"
click node_entry "https://github.com/miraliog/pelegram/blob/main/src/HandlerEntry.php"
click node_filters "https://github.com/miraliog/pelegram/tree/main/src/Filters"
click node_middleware "https://github.com/miraliog/pelegram/blob/main/src/Contracts/MiddlewareInterface.php"
click node_state "https://github.com/miraliog/pelegram/blob/main/src/State/State.php"
click node_state_data "https://github.com/miraliog/pelegram/blob/main/src/State/StateData.php"
click node_state_drivers "https://github.com/miraliog/pelegram/tree/main/src/State/Drivers"
click node_bot "https://github.com/miraliog/pelegram/blob/main/src/Bot.php"
click node_enums "https://github.com/miraliog/pelegram/tree/main/src/Enums"
click node_reply_keyboard "https://github.com/miraliog/pelegram/blob/main/src/Types/Keyboard/ReplyKeyboardMarkup.php"
click node_inline_keyboard "https://github.com/miraliog/pelegram/blob/main/src/Types/Keyboard/InlineKeyboardMarkup.php"
click node_keyboard_buttons "https://github.com/miraliog/pelegram/blob/main/src/Types/Keyboard/KeyboardButton.php"
click node_inline_buttons "https://github.com/miraliog/pelegram/blob/main/src/Types/Keyboard/InlineKeyboardButton.php"
click node_remove_keyboard "https://github.com/miraliog/pelegram/blob/main/src/Types/Keyboard/ReplyKeyboardRemove.php"

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_update,node_accessors,node_detect,node_message,node_callback,node_inline toneBlue
class node_router,node_entry,node_filters,node_middleware,node_state,node_state_data,node_state_drivers toneAmber
class node_bot,node_enums toneMint
class node_reply_keyboard,node_inline_keyboard,node_keyboard_buttons,node_inline_buttons,node_remove_keyboard toneRose
class node_telegram,node_app toneIndigo
```

## Components

### Updates and types

- [Webhook update](https://github.com/miraliog/pelegram/blob/main/src/Update.php): `src/Update.php`
- [Update accessors](https://github.com/miraliog/pelegram/tree/main/src/Concerns/Accessors): `src/Concerns/Accessors`
- [Update detection](https://github.com/miraliog/pelegram/tree/main/src/Concerns/Update): `src/Concerns/Update`
- [Message](https://github.com/miraliog/pelegram/blob/main/src/Types/Message.php): `src/Types/Message.php`
- [Callback query](https://github.com/miraliog/pelegram/blob/main/src/Types/CallbackQuery.php): `src/Types/CallbackQuery.php`
- [Inline query](https://github.com/miraliog/pelegram/blob/main/src/Types/InlineQuery.php): `src/Types/InlineQuery.php`

### Routing and state

- [Router](https://github.com/miraliog/pelegram/blob/main/src/Router.php): `src/Router.php`
- [Handler entry](https://github.com/miraliog/pelegram/blob/main/src/HandlerEntry.php): `src/HandlerEntry.php`
- [Filters](https://github.com/miraliog/pelegram/tree/main/src/Filters): `src/Filters`
- [Middleware](https://github.com/miraliog/pelegram/blob/main/src/Contracts/MiddlewareInterface.php): `src/Contracts/MiddlewareInterface.php`
- [User state](https://github.com/miraliog/pelegram/blob/main/src/State/State.php): `src/State/State.php`
- [State data](https://github.com/miraliog/pelegram/blob/main/src/State/StateData.php): `src/State/StateData.php`
- [State drivers](https://github.com/miraliog/pelegram/tree/main/src/State/Drivers): `src/State/Drivers`

### Telegram API

- [Bot API client](https://github.com/miraliog/pelegram/blob/main/src/Bot.php): `src/Bot.php`
- [API enums](https://github.com/miraliog/pelegram/tree/main/src/Enums): `src/Enums`

### Keyboards

- [Reply keyboards](https://github.com/miraliog/pelegram/blob/main/src/Types/Keyboard/ReplyKeyboardMarkup.php): `src/Types/Keyboard/ReplyKeyboardMarkup.php`
- [Inline keyboards](https://github.com/miraliog/pelegram/blob/main/src/Types/Keyboard/InlineKeyboardMarkup.php): `src/Types/Keyboard/InlineKeyboardMarkup.php`
- [Keyboard buttons](https://github.com/miraliog/pelegram/blob/main/src/Types/Keyboard/KeyboardButton.php): `src/Types/Keyboard/KeyboardButton.php`
- [Inline buttons](https://github.com/miraliog/pelegram/blob/main/src/Types/Keyboard/InlineKeyboardButton.php): `src/Types/Keyboard/InlineKeyboardButton.php`
- [Keyboard removal](https://github.com/miraliog/pelegram/blob/main/src/Types/Keyboard/ReplyKeyboardRemove.php): `src/Types/Keyboard/ReplyKeyboardRemove.php`

### Other components

- **Telegram**
- **Bot application**

## Connections

- Telegram → Webhook update: delivers webhook
- Bot application → Router: dispatches bot
- Router → Webhook update: routes update (evidence: `src/Router.php`)
- Webhook update → Update accessors: uses traits (evidence: `src/Update.php`)
- Webhook update → Update detection: uses traits (evidence: `src/Update.php`)
- Router → Handler entry: registers handlers (evidence: `src/Router.php`)
- Handler entry → Filters: checks filters (evidence: `src/HandlerEntry.php`)
- Router → Filters: applies filters (evidence: `src/Router.php`)
- Router → Middleware: runs middleware (evidence: `src/Router.php`)
- Router → Message: constructs message (evidence: `src/Router.php`)
- Router → Callback query: constructs query (evidence: `src/Router.php`)
- Router → Inline query: constructs query (evidence: `src/Router.php`)
- Router → User state: loads state (evidence: `src/Router.php`)
- User state → State data: provides data (evidence: `src/State/State.php`)
- User state → State drivers: uses driver (evidence: `src/State/State.php`)
- Message → Bot API client: calls API (evidence: `src/Types/Message.php`)
- Callback query → Bot API client: calls API (evidence: `src/Types/CallbackQuery.php`)
- Inline query → Bot API client: calls API (evidence: `src/Types/InlineQuery.php`)
- Bot API client → Telegram: sends API requests (evidence: `src/Bot.php`)
- Reply keyboards → Keyboard buttons: contains buttons (evidence: `src/Types/Keyboard/ReplyKeyboardMarkup.php`)
- Inline keyboards → Inline buttons: contains buttons (evidence: `src/Types/Keyboard/InlineKeyboardMarkup.php`)
- Message → Reply keyboards: accepts markup (evidence: `src/Types/Message.php`)
- Message → Inline keyboards: accepts markup (evidence: `src/Types/Message.php`)
- Message → Keyboard removal: accepts markup (evidence: `src/Types/Message.php`)
- Bot API client → Reply keyboards: serializes markup (evidence: `src/Bot.php`)
- Bot API client → Inline keyboards: serializes markup (evidence: `src/Bot.php`)
- Bot API client → Keyboard removal: serializes markup (evidence: `src/Bot.php`)
