# wakaree/aiogram_bot_template architecture

> Architecture diagram of the GitHub repository wakaree/aiogram_bot_template, 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/wakaree/aiogram_bot_template
- Repository: https://github.com/wakaree/aiogram_bot_template

## Overview

This is a reusable aiogram Telegram bot template with FastAPI hosting, configurable polling/webhook startup, localization, persistence, and Redis-backed state/cache. Its principal user path is Telegram update → handler → flow → interactor/presenter → view renderer → Telegram response. The README documents this sequence; source evidence is sampled, so unsampled feature-level calls and repository wiring are not asserted. Major feature areas are represented at their exact tree paths.

Main entry points: [`app/presentation/telegram/handlers`](https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/handlers) (Update handlers), [`app/runners/app.py`](https://github.com/wakaree/aiogram_bot_template/blob/main/app/runners/app.py) (App runner), [`app/presentation/telegram/flows`](https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/flows) (Interaction flows), [`app/application/ports/repositories/users.py`](https://github.com/wakaree/aiogram_bot_template/blob/main/app/application/ports/repositories/users.py) (Users gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and delivery"]
  node_runner["App runner<br/>[app.py]"]
  node_webhook_api["Webhook API<br/>[telegram.py]"]
  node_health["Health check<br/>[healthcheck.py]"]
  node_dispatcher["Dispatcher setup<br/>[dispatcher.py]"]
  node_di["Dependency wiring<br/>[container.py]"]
  node_lifespan["Bot lifecycle<br/>[lifespan.py]"]
  node_config_provider["Settings provider<br/>[app.py]"]
end

subgraph group_bot["Telegram interaction"]
  node_handlers["Update handlers"]
  node_flows["Interaction flows"]
  node_presenters["View presenters"]
  node_views["View models<br/>[models.py]"]
  node_renderer["Bot renderer<br/>[renderer.py]"]
  node_keyboards["Keyboard builders"]
  node_callbacks["Callback data"]
  node_filters["Update filters"]
  node_middlewares["Request middleware"]
  node_message_helper["Message helper<br/>[messages.py]"]
end

subgraph group_core["Application and domain"]
  node_interactors["Use-case logic"]
  node_user_domain["User domain model<br/>[user.py]"]
  node_user_status["User status use case<br/>[user_status.py]"]
  node_user_port["Users gateway<br/>[users.py]"]
  node_config["Application settings<br/>[app.py]"]
end

subgraph group_infra["Infrastructure"]
  node_user_repo["Postgres user repository<br/>[users.py]"]
  node_uow["Postgres unit of work<br/>[uow.py]"]
  node_postgres[("PostgreSQL")]
  node_kv_repo["Redis key-value store<br/>[repository.py]"]
  node_redis[("Redis")]
  node_cache_service["Redis cache service<br/>[service.py]"]
  node_localization["Localization manager<br/>[manager.py]"]
end

node_telegram_user(("Telegram user"))
node_telegram_service(("Telegram Bot API"))

node_runner -->|"registers webhook"| node_webhook_api
node_runner -->|"configures runtime"| node_dispatcher
node_runner -->|"starts lifecycle"| node_lifespan
node_runner -->|"sets up routes"| node_health
node_runner -->|"resolves dependencies"| node_di
node_config_provider -->|"constructs settings"| node_config
node_telegram_user -.->|"sends update"| node_webhook_api
node_webhook_api -.->|"dispatches update"| node_dispatcher
node_dispatcher -->|"registers routers"| node_handlers
node_handlers -.->|"calls flow"| node_flows
node_flows -.->|"orchestrates use case"| node_interactors
node_flows -.->|"invokes presenter"| node_presenters
node_presenters -.->|"builds view"| node_views
node_flows -.->|"calls renderer"| node_renderer
node_renderer -.->|"sends response"| node_telegram_service
node_telegram_user -.->|"sends update"| node_handlers
node_handlers -.->|"uses filters"| node_filters
node_handlers -.->|"uses middleware"| node_middlewares
node_presenters -.->|"uses builders"| node_keyboards
node_handlers -.->|"processes callbacks"| node_callbacks
node_interactors -.->|"uses gateway"| node_user_port
node_user_port -.->|"implemented by"| node_user_repo
node_user_repo -.->|"uses unit of work"| node_uow
node_uow -.->|"reads and writes"| node_postgres
node_user_domain -.->|"persisted as entity"| node_user_repo
node_user_status -.->|"uses gateway"| node_user_port
node_kv_repo -.->|"reads and writes"| node_redis
node_cache_service -->|"reads and writes"| node_redis
node_cache_service -.->|"separate storage service"| node_kv_repo
node_localization -->|"saves locale"| node_user_port
node_localization -->|"reads and updates"| node_user_domain
node_message_helper -.->|"messaging support"| node_telegram_service
node_lifespan -->|"configures bot"| node_telegram_service
node_lifespan -->|"stores setup locks"| node_kv_repo

click node_runner "https://github.com/wakaree/aiogram_bot_template/blob/main/app/runners/app.py"
click node_webhook_api "https://github.com/wakaree/aiogram_bot_template/blob/main/app/presentation/fastapi/telegram.py"
click node_health "https://github.com/wakaree/aiogram_bot_template/blob/main/app/presentation/fastapi/healthcheck.py"
click node_dispatcher "https://github.com/wakaree/aiogram_bot_template/blob/main/app/providers/telegram/dispatcher.py"
click node_di "https://github.com/wakaree/aiogram_bot_template/blob/main/app/providers/container.py"
click node_lifespan "https://github.com/wakaree/aiogram_bot_template/blob/main/app/infrastructure/telegram/lifespan.py"
click node_handlers "https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/handlers"
click node_flows "https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/flows"
click node_interactors "https://github.com/wakaree/aiogram_bot_template/tree/main/app/application/interactors"
click node_presenters "https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/presenters"
click node_views "https://github.com/wakaree/aiogram_bot_template/blob/main/app/presentation/telegram/view/models.py"
click node_renderer "https://github.com/wakaree/aiogram_bot_template/blob/main/app/presentation/telegram/view/renderer.py"
click node_keyboards "https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/keyboards"
click node_callbacks "https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/callbacks"
click node_filters "https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/filters"
click node_middlewares "https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/middlewares"
click node_user_domain "https://github.com/wakaree/aiogram_bot_template/blob/main/app/domain/user.py"
click node_user_status "https://github.com/wakaree/aiogram_bot_template/blob/main/app/application/interactors/pm/user_status.py"
click node_user_port "https://github.com/wakaree/aiogram_bot_template/blob/main/app/application/ports/repositories/users.py"
click node_user_repo "https://github.com/wakaree/aiogram_bot_template/blob/main/app/infrastructure/postgres/repositories/users.py"
click node_uow "https://github.com/wakaree/aiogram_bot_template/blob/main/app/infrastructure/postgres/uow.py"
click node_kv_repo "https://github.com/wakaree/aiogram_bot_template/blob/main/app/infrastructure/redis/repository.py"
click node_cache_service "https://github.com/wakaree/aiogram_bot_template/blob/main/app/infrastructure/redis/cache/service.py"
click node_localization "https://github.com/wakaree/aiogram_bot_template/blob/main/app/infrastructure/localization/manager.py"
click node_message_helper "https://github.com/wakaree/aiogram_bot_template/blob/main/app/presentation/telegram/helpers/messages.py"
click node_config "https://github.com/wakaree/aiogram_bot_template/blob/main/app/application/models/config/env/app.py"
click node_config_provider "https://github.com/wakaree/aiogram_bot_template/blob/main/app/providers/infrastructure/app.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_runner,node_webhook_api,node_health,node_dispatcher,node_di,node_lifespan,node_config_provider,node_telegram_user toneBlue
class node_handlers,node_flows,node_presenters,node_views,node_renderer,node_keyboards,node_callbacks,node_filters,node_middlewares,node_message_helper toneAmber
class node_interactors,node_user_domain,node_user_status,node_user_port,node_config,node_telegram_service toneMint
class node_user_repo,node_uow,node_postgres,node_kv_repo,node_redis,node_cache_service,node_localization toneRose
```

## Components

### Runtime and delivery

- [App runner](https://github.com/wakaree/aiogram_bot_template/blob/main/app/runners/app.py): `app/runners/app.py`
- [Webhook API](https://github.com/wakaree/aiogram_bot_template/blob/main/app/presentation/fastapi/telegram.py): `app/presentation/fastapi/telegram.py`
- [Health check](https://github.com/wakaree/aiogram_bot_template/blob/main/app/presentation/fastapi/healthcheck.py): `app/presentation/fastapi/healthcheck.py`
- [Dispatcher setup](https://github.com/wakaree/aiogram_bot_template/blob/main/app/providers/telegram/dispatcher.py): `app/providers/telegram/dispatcher.py`
- [Dependency wiring](https://github.com/wakaree/aiogram_bot_template/blob/main/app/providers/container.py): `app/providers/container.py`
- [Bot lifecycle](https://github.com/wakaree/aiogram_bot_template/blob/main/app/infrastructure/telegram/lifespan.py): `app/infrastructure/telegram/lifespan.py`
- [Settings provider](https://github.com/wakaree/aiogram_bot_template/blob/main/app/providers/infrastructure/app.py): `app/providers/infrastructure/app.py`

### Telegram interaction

- [Update handlers](https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/handlers): `app/presentation/telegram/handlers`
- [Interaction flows](https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/flows): `app/presentation/telegram/flows`
- [View presenters](https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/presenters): `app/presentation/telegram/presenters`
- [View models](https://github.com/wakaree/aiogram_bot_template/blob/main/app/presentation/telegram/view/models.py): `app/presentation/telegram/view/models.py`
- [Bot renderer](https://github.com/wakaree/aiogram_bot_template/blob/main/app/presentation/telegram/view/renderer.py): `app/presentation/telegram/view/renderer.py`
- [Keyboard builders](https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/keyboards): `app/presentation/telegram/keyboards`
- [Callback data](https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/callbacks): `app/presentation/telegram/callbacks`
- [Update filters](https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/filters): `app/presentation/telegram/filters`
- [Request middleware](https://github.com/wakaree/aiogram_bot_template/tree/main/app/presentation/telegram/middlewares): `app/presentation/telegram/middlewares`
- [Message helper](https://github.com/wakaree/aiogram_bot_template/blob/main/app/presentation/telegram/helpers/messages.py): `app/presentation/telegram/helpers/messages.py`

### Application and domain

- [Use-case logic](https://github.com/wakaree/aiogram_bot_template/tree/main/app/application/interactors): `app/application/interactors`
- [User domain model](https://github.com/wakaree/aiogram_bot_template/blob/main/app/domain/user.py): `app/domain/user.py`
- [User status use case](https://github.com/wakaree/aiogram_bot_template/blob/main/app/application/interactors/pm/user_status.py): `app/application/interactors/pm/user_status.py`
- [Users gateway](https://github.com/wakaree/aiogram_bot_template/blob/main/app/application/ports/repositories/users.py): `app/application/ports/repositories/users.py`
- [Application settings](https://github.com/wakaree/aiogram_bot_template/blob/main/app/application/models/config/env/app.py): `app/application/models/config/env/app.py`

### Infrastructure

- [Postgres user repository](https://github.com/wakaree/aiogram_bot_template/blob/main/app/infrastructure/postgres/repositories/users.py): `app/infrastructure/postgres/repositories/users.py`
- [Postgres unit of work](https://github.com/wakaree/aiogram_bot_template/blob/main/app/infrastructure/postgres/uow.py): `app/infrastructure/postgres/uow.py`
- **PostgreSQL**
- [Redis key-value store](https://github.com/wakaree/aiogram_bot_template/blob/main/app/infrastructure/redis/repository.py): `app/infrastructure/redis/repository.py`
- **Redis**
- [Redis cache service](https://github.com/wakaree/aiogram_bot_template/blob/main/app/infrastructure/redis/cache/service.py): `app/infrastructure/redis/cache/service.py`
- [Localization manager](https://github.com/wakaree/aiogram_bot_template/blob/main/app/infrastructure/localization/manager.py): `app/infrastructure/localization/manager.py`

### Other components

- **Telegram user**
- **Telegram Bot API**

## Connections

- App runner → Webhook API: registers webhook (evidence: `app/runners/app.py`)
- App runner → Dispatcher setup: configures runtime (evidence: `app/runners/app.py`)
- App runner → Bot lifecycle: starts lifecycle (evidence: `app/runners/app.py`)
- App runner → Health check: sets up routes
- App runner → Dependency wiring: resolves dependencies (evidence: `app/__main__.py`)
- Settings provider → Application settings: constructs settings (evidence: `app/providers/infrastructure/app.py`)
- Telegram user → Webhook API: sends update (evidence: `README.md`)
- Webhook API → Dispatcher setup: dispatches update (evidence: `README.md`)
- Dispatcher setup → Update handlers: registers routers (evidence: `app/providers/telegram/dispatcher.py`)
- Update handlers → Interaction flows: calls flow (evidence: `README.md`)
- Interaction flows → Use-case logic: orchestrates use case (evidence: `README.md`)
- Interaction flows → View presenters: invokes presenter (evidence: `README.md`)
- View presenters → View models: builds view (evidence: `README.md`)
- Interaction flows → Bot renderer: calls renderer (evidence: `README.md`)
- Bot renderer → Telegram Bot API: sends response (evidence: `README.md`)
- Telegram user → Update handlers: sends update (evidence: `README.md`)
- Update handlers → Update filters: uses filters
- Update handlers → Request middleware: uses middleware (evidence: `app/providers/telegram/dispatcher.py`)
- View presenters → Keyboard builders: uses builders
- Update handlers → Callback data: processes callbacks
- Use-case logic → Users gateway: uses gateway
- Users gateway → Postgres user repository: implemented by
- Postgres user repository → Postgres unit of work: uses unit of work
- Postgres unit of work → PostgreSQL: reads and writes
- User domain model → Postgres user repository: persisted as entity
- User status use case → Users gateway: uses gateway
- Redis key-value store → Redis: reads and writes
- Redis cache service → Redis: reads and writes (evidence: `app/infrastructure/redis/cache/service.py`)
- Redis cache service → Redis key-value store: separate storage service
- Localization manager → Users gateway: saves locale (evidence: `app/infrastructure/localization/manager.py`)
- Localization manager → User domain model: reads and updates (evidence: `app/infrastructure/localization/manager.py`)
- Message helper → Telegram Bot API: messaging support
- Bot lifecycle → Telegram Bot API: configures bot (evidence: `app/infrastructure/telegram/lifespan.py`)
- Bot lifecycle → Redis key-value store: stores setup locks (evidence: `app/infrastructure/telegram/lifespan.py`)
