# uladzislautsimankou/telegram-botkit architecture

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

- Interactive diagram: https://gitdiagram.com/uladzislautsimankou/telegram-botkit
- Repository: https://github.com/uladzislautsimankou/telegram-botkit

## Overview

#### Purpose and entry points
Telegram.BotKit is a .NET 10 library for Telegram bots, built atop the external `Telegram.Bot` client. It provides DI-driven handler registration, typed parameter binding, and separate middleware pipelines for update types. The runnable reference host starts at `Telegram.BotKit.Example/Program.cs`; library consumers configure and build a bot through `Telegram.BotKit/Hosting/BotBuilder.cs` and `Telegram.BotKit/Hosting/BotApplication.cs`.

#### Update ingress and hosting
Telegram updates enter through one of two transport modes:
- Long polling: `Telegram.BotKit/Hosting/Background/PollingService.cs` runs as a hosted background service.
- ASP.NET Core webhook: `Telegram.BotKit/Hosting/Webhook/BotController.cs` receives updates, with setup managed by `Telegram.BotKit/Hosting/Webhook/WebhookStartupService.cs`.
Both paths hand updates to the central update handler, normally `Telegram.BotKit/DefaultUpdateHandler.cs`; applications may supply their own, as demonstrated by `Telegram.BotKit.Example/Services/GlobalUpdateHandler.cs`.

#### Update classification and dispatch
`DefaultUpdateHandler` classifies Telegram update payloads into commands, callbacks, inline queries, or ordinary messages and delegates to dedicated dispatchers:
- `Telegram.BotKit/Pipeline/Dispatchers/CommandDispatcher.cs`
- `Telegram.BotKit/Pipeline/Dispatchers/CallbackDispatcher.cs`
- `Telegram.BotKit/Pipeline/Dispatchers/InlineQueryDispatcher.cs`
- `Telegram.BotKit/Pipeline/Dispatchers/MessageDispatcher.cs`
Each dispatcher owns a type-specific pipeline and context model, isolating behavior and failure handling by interaction type.

#### Middleware and routing boundary
Pipelines compose framework defaults with user-registered middleware interfaces under `Telegram.BotKit/Abstractions`. Command and message pipelines separate routing from execution; callback and inline-query pipelines route directly to invocation. Core stages include command routing/execution (`Telegram.BotKit/Pipeline/Middlewares/Commands/CommandRoutingMiddleware.cs`, `Telegram.BotKit/Pipeline/Middlewares/Commands/CommandExecutionMiddleware.cs`), callback routing, inline query routing, and message routing/execution. Default per-pipeline error boundaries convert routing, binding, and handler failures through error-handler middleware.

#### Handler contracts, discovery, and invocation
Bot behavior is implemented through typed handler interfaces: commands, callbacks, inline queries, and messages in `Telegram.BotKit/Abstractions/Commands/ICommandHandler.cs`, `Telegram.BotKit/Abstractions/Callbacks/ICallbackHandler.cs`, and `Telegram.BotKit/Abstractions/Messages/IMessageHandler.cs`. Routing selects handlers by command/key/query/message eligibility; invokers construct typed calls and invoke handlers:
`Telegram.BotKit/Invocation/CommandHandlerInvoker.cs`,
`Telegram.BotKit/Invocation/CallbackHandlerInvoker.cs`, and
`Telegram.BotKit/Invocation/InlineQueryHandlerInvoker.cs`.
DI registration is centralized in `Telegram.BotKit/Extensions/ServiceCollectionExtensions.cs` and `Telegram.BotKit/Extensions/ServicesRegistrationExtention.cs`.

#### Parsing and strongly typed binding
Raw Telegram text/query payloads cross into application DTOs through parsers and binders. Commands use `Telegram.BotKit/Binding/Parsers/CommandParser.cs` plus `Telegram.BotKit/Binding/Binders/CommandParameterBinder.cs`; callbacks and inline queries use their corresponding parser/binder pairs. Attributes in `Telegram.BotKit/Attributes/CommandParamAttribute.cs` and `Telegram.BotKit/Attributes/InlineQyeryParamAttribute.cs` describe DTO mapping, while `Telegram.BotKit/Binding/Converters/DefaultValueConverter.cs` supplies default scalar conversion. Unknown-command handling is assisted by `Telegram.BotKit/Helpers/CommandSearcher.cs`.

#### Stateful messages and application extension points
Message contexts can carry conversational state, loaded before message routing by `IMessageStateMiddleware` and the framework default in `Telegram.BotKit/Pipeline/Middlewares/Messages/DefaultMessageStateMiddleware.cs`. State persistence itself remains application-owned. The example demonstrates extension points via concrete handlers in `Telegram.BotKit.Example/Handlers`, custom error/logging middleware in `Telegram.BotKit.Example/Middlewares`, and application configuration in `Telegram.BotKit.Example/appsettings.json`.

Main entry points: [`Telegram.BotKit/Hosting/BotApplication.cs`](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Hosting/BotApplication.cs) (Bot application), [`Telegram.BotKit/Pipeline/Dispatchers/CommandDispatcher.cs`](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Pipeline/Dispatchers/CommandDispatcher.cs) (Type dispatchers), [`Telegram.BotKit/Pipeline/Middlewares/Commands/CommandRoutingMiddleware.cs`](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Pipeline/Middlewares/Commands/CommandRoutingMiddleware.cs) (Command routing and execution), [`Telegram.BotKit/Pipeline/Dispatchers/CallbackDispatcher.cs`](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Pipeline/Dispatchers/CallbackDispatcher.cs) (Callback and inline routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hosting["Hosting"]
  node_bot_builder["Bot builder<br/>hosting API<br/>[BotBuilder.cs]"]
  node_bot_application["Bot application<br/>application host<br/>[BotApplication.cs]"]
  node_service_registration["DI registration<br/>service registration"]
  node_telegram_client{{"Telegram.Bot client<br/>external client"}}
  node_polling["Long polling<br/>hosted service<br/>[PollingService.cs]"]
  node_webhook["Webhook endpoint<br/>ASP.NET controller<br/>[BotController.cs]"]
  node_webhook_setup["Webhook setup<br/>startup service"]
end

subgraph group_pipeline["Update pipelines"]
  node_update_handler["Update handler<br/>update boundary"]
  node_dispatchers["Type dispatchers<br/>pipelines"]
  node_command_pipeline["Command routing and execution<br/>middleware stages"]
  node_interaction_pipelines["Callback and inline routing<br/>middleware stages"]
  node_message_pipeline["Message state and execution<br/>middleware stages"]
  node_error_middleware["Pipeline error boundaries<br/>middleware"]
end

subgraph group_binding["Binding and invocation"]
  node_parsers_binders["Parsers and typed binders<br/>binding layer<br/>[CommandParser.cs]"]
  node_handler_invokers["Handler invokers<br/>invocation layer"]
  node_handler_contracts["Handler contracts<br/>handler interfaces<br/>[ICommandHandler.cs]"]
end

subgraph group_application["Application extensions"]
  node_example_host["Reference host<br/>.NET host<br/>[Program.cs]"]
  node_app_handlers["Application handlers<br/>bot behavior<br/>[Handlers]"]
  node_custom_update_handler["Custom update handler<br/>update extension"]
end

node_example_host -->|"configures"| node_bot_builder
node_bot_builder -->|"builds"| node_bot_application
node_bot_builder -->|"registers"| node_service_registration
node_service_registration -->|"discovers and registers"| node_handler_contracts
node_bot_application -->|"hosts"| node_polling
node_bot_application -->|"hosts"| node_webhook
node_bot_application -->|"starts"| node_webhook_setup
node_polling -->|"receives updates"| node_telegram_client
node_webhook_setup -->|"configures webhook"| node_telegram_client
node_telegram_client -.->|"delivers updates"| node_webhook
node_polling -->|"forwards update"| node_update_handler
node_webhook -->|"forwards update"| node_update_handler
node_custom_update_handler -.->|"may replace"| node_update_handler
node_update_handler -->|"classifies and delegates"| node_dispatchers
node_dispatchers -->|"command updates"| node_command_pipeline
node_dispatchers -->|"callback and inline updates"| node_interaction_pipelines
node_dispatchers -->|"message updates"| node_message_pipeline
node_command_pipeline -->|"parses and binds"| node_parsers_binders
node_interaction_pipelines -->|"parses and binds"| node_parsers_binders
node_parsers_binders -->|"typed arguments"| node_handler_invokers
node_command_pipeline -->|"selected handler"| node_handler_invokers
node_interaction_pipelines -->|"selected handler"| node_handler_invokers
node_message_pipeline -->|"invokes eligible handler"| node_handler_contracts
node_handler_invokers -->|"invokes contract"| node_handler_contracts
node_handler_contracts -->|"implemented by"| node_app_handlers
node_command_pipeline -.->|"failures handled by"| node_error_middleware
node_interaction_pipelines -.->|"failures handled by"| node_error_middleware
node_message_pipeline -.->|"failures handled by"| node_error_middleware

click node_example_host "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit.Example/Program.cs"
click node_bot_builder "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Hosting/BotBuilder.cs"
click node_bot_application "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Hosting/BotApplication.cs"
click node_service_registration "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Extensions/ServiceCollectionExtensions.cs"
click node_polling "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Hosting/Background/PollingService.cs"
click node_webhook "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Hosting/Webhook/BotController.cs"
click node_webhook_setup "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Hosting/Webhook/WebhookStartupService.cs"
click node_update_handler "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/DefaultUpdateHandler.cs"
click node_dispatchers "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Pipeline/Dispatchers/CommandDispatcher.cs"
click node_command_pipeline "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Pipeline/Middlewares/Commands/CommandRoutingMiddleware.cs"
click node_interaction_pipelines "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Pipeline/Dispatchers/CallbackDispatcher.cs"
click node_message_pipeline "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Pipeline/Middlewares/Messages/DefaultMessageStateMiddleware.cs"
click node_parsers_binders "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Binding/Parsers/CommandParser.cs"
click node_handler_invokers "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Invocation/CommandHandlerInvoker.cs"
click node_handler_contracts "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Abstractions/Commands/ICommandHandler.cs"
click node_app_handlers "https://github.com/uladzislautsimankou/telegram-botkit/tree/main/Telegram.BotKit.Example/Handlers"
click node_custom_update_handler "https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit.Example/Services/GlobalUpdateHandler.cs"

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_builder,node_bot_application,node_service_registration,node_telegram_client,node_polling,node_webhook,node_webhook_setup toneBlue
class node_update_handler,node_dispatchers,node_command_pipeline,node_interaction_pipelines,node_message_pipeline,node_error_middleware toneAmber
class node_parsers_binders,node_handler_invokers,node_handler_contracts toneMint
class node_example_host,node_app_handlers,node_custom_update_handler toneRose
```

## Components

### Hosting

- [Bot builder](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Hosting/BotBuilder.cs): hosting API · Consumer-facing bot configuration and construction. · `Telegram.BotKit/Hosting/BotBuilder.cs`
- [Bot application](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Hosting/BotApplication.cs): application host · `Telegram.BotKit/Hosting/BotApplication.cs`
- [DI registration](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Extensions/ServiceCollectionExtensions.cs): service registration · Registers framework services and discovered handlers. · `Telegram.BotKit/Extensions/ServiceCollectionExtensions.cs`
- **Telegram.Bot client**: external client · External Telegram API client.
- [Long polling](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Hosting/Background/PollingService.cs): hosted service · `Telegram.BotKit/Hosting/Background/PollingService.cs`
- [Webhook endpoint](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Hosting/Webhook/BotController.cs): ASP.NET controller · `Telegram.BotKit/Hosting/Webhook/BotController.cs`
- [Webhook setup](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Hosting/Webhook/WebhookStartupService.cs): startup service · `Telegram.BotKit/Hosting/Webhook/WebhookStartupService.cs`

### Update pipelines

- [Update handler](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/DefaultUpdateHandler.cs): update boundary · Classifies each incoming Telegram update. · `Telegram.BotKit/DefaultUpdateHandler.cs`
- [Type dispatchers](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Pipeline/Dispatchers/CommandDispatcher.cs): pipelines · Separate command, callback, inline-query, and message pipelines. · `Telegram.BotKit/Pipeline/Dispatchers/CommandDispatcher.cs`
- [Command routing and execution](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Pipeline/Middlewares/Commands/CommandRoutingMiddleware.cs): middleware stages · Routes commands, then binds and executes handlers. · `Telegram.BotKit/Pipeline/Middlewares/Commands/CommandRoutingMiddleware.cs`
- [Callback and inline routing](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Pipeline/Dispatchers/CallbackDispatcher.cs): middleware stages · Route callbacks and inline queries directly to invocation. · `Telegram.BotKit/Pipeline/Dispatchers/CallbackDispatcher.cs`
- [Message state and execution](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Pipeline/Middlewares/Messages/DefaultMessageStateMiddleware.cs): middleware stages · Loads conversational state before message routing and execution. · `Telegram.BotKit/Pipeline/Middlewares/Messages/DefaultMessageStateMiddleware.cs`
- **Pipeline error boundaries**: middleware · Converts routing, binding, and handler failures.

### Binding and invocation

- [Parsers and typed binders](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Binding/Parsers/CommandParser.cs): binding layer · Parses payloads and maps parameters into DTOs. · `Telegram.BotKit/Binding/Parsers/CommandParser.cs`
- [Handler invokers](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Invocation/CommandHandlerInvoker.cs): invocation layer · Constructs typed calls to selected handlers. · `Telegram.BotKit/Invocation/CommandHandlerInvoker.cs`
- [Handler contracts](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit/Abstractions/Commands/ICommandHandler.cs): handler interfaces · Command, callback, inline-query, and message extension contracts. · `Telegram.BotKit/Abstractions/Commands/ICommandHandler.cs`

### Application extensions

- [Reference host](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit.Example/Program.cs): .NET host · Configures and runs a sample bot. · `Telegram.BotKit.Example/Program.cs`
- [Application handlers](https://github.com/uladzislautsimankou/telegram-botkit/tree/main/Telegram.BotKit.Example/Handlers): bot behavior · Concrete handlers implement application behavior. · `Telegram.BotKit.Example/Handlers`
- [Custom update handler](https://github.com/uladzislautsimankou/telegram-botkit/blob/main/Telegram.BotKit.Example/Services/GlobalUpdateHandler.cs): update extension · Optional replacement for the framework update handler. · `Telegram.BotKit.Example/Services/GlobalUpdateHandler.cs`

## Connections

- Reference host → Bot builder: configures
- Bot builder → Bot application: builds
- Bot builder → DI registration: registers
- DI registration → Handler contracts: discovers and registers
- Bot application → Long polling: hosts
- Bot application → Webhook endpoint: hosts
- Bot application → Webhook setup: starts
- Long polling → Telegram.Bot client: receives updates
- Webhook setup → Telegram.Bot client: configures webhook
- Telegram.Bot client → Webhook endpoint: delivers updates
- Long polling → Update handler: forwards update
- Webhook endpoint → Update handler: forwards update
- Custom update handler → Update handler: may replace
- Update handler → Type dispatchers: classifies and delegates
- Type dispatchers → Command routing and execution: command updates
- Type dispatchers → Callback and inline routing: callback and inline updates
- Type dispatchers → Message state and execution: message updates
- Command routing and execution → Parsers and typed binders: parses and binds
- Callback and inline routing → Parsers and typed binders: parses and binds
- Parsers and typed binders → Handler invokers: typed arguments
- Command routing and execution → Handler invokers: selected handler
- Callback and inline routing → Handler invokers: selected handler
- Message state and execution → Handler contracts: invokes eligible handler
- Handler invokers → Handler contracts: invokes contract
- Handler contracts → Application handlers: implemented by
- Command routing and execution → Pipeline error boundaries: failures handled by
- Callback and inline routing → Pipeline error boundaries: failures handled by
- Message state and execution → Pipeline error boundaries: failures handled by