# hexdevop/aiogram_sqlalchemy_replication architecture

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

- Interactive diagram: https://gitdiagram.com/hexdevop/aiogram_sqlalchemy_replication
- Repository: https://github.com/hexdevop/aiogram_sqlalchemy_replication

## Overview

##### Project Type and Purpose
- This is a lightweight, monolithic Telegram bot template built with aiogram v3. It demonstrates asynchronous message handling and MySQL replication for read‑write separation and high availability.
- Key use cases: receiving updates from Telegram, processing them via handlers, storing/retrieving data in a master‑replica MySQL setup, and sending responses with custom keyboards.

##### High‑Level Architectural Components
a. Telegram Bot API (External Service)
- Long‑polling or webhook endpoint that delivers updates to your bot.
b. Bot Core (main.py, config.py, settings.json)
- Initializes the aiogram Dispatcher, registers middlewares, filters, handlers, and the database engine.
c. Dispatcher & Event Loop (aiogram framework)
- Routes incoming updates through filters → middlewares → handlers.
d. Filters (bot/filters)
- chat_type.py: pre‑handler logic that selects only certain chat types.
e. Middlewares (bot/middlewares)
- database.py: attaches a DB session/connection to each update’s context.
f. Handlers (bot/handlers)
- Default handlers for errors and blocks.
- Channel‑specific handlers.
- Chat handlers.
- User handlers (deep_link, main/start).
g. UI Components (bot/keyboards)
- factory.py: centralized keyboard creation.
- inline.py, reply.py: define button layouts.
h. Finite State Machine (bot/states.py)
- Tracks multi‑step user interactions.
i. Database Engine (bot/database/engine)
- manager.py: sets up SQLAlchemy engines for master (writes) and replicas (reads).
- routing.py: custom session/connection router that sends reads to replicas and writes to master.
j. ORM Models (bot/database/models)
- base.py: common declarative base.
- default.py: sample models/datatypes.
k. Data Storage (MySQL Master + Replicas)
- Master handles INSERT/UPDATE/DELETE.
- One or more replicas handle SELECT queries.
l. External Dependencies
- aiogram, SQLAlchemy, MySQL driver.

##### Relationships and Data Flows
- Telegram API → Bot Core (main.py) → Dispatcher
- Incoming Update → Filter(chat_type) → Middleware(DB session) → Handler
- Handler business logic → invokes ORM via session
- Writes → master engine via routing
- Reads → replica engine via routing
- Handler builds response using keyboards and sends back to Telegram API.
- The FSM module coordinates multi‑step dialogs by storing state in memory or DB.
- Settings.json & config.py provide DB credentials, replica addresses, bot token.

##### Architectural Patterns and Principles
- Layered Architecture: presentation (Telegram), application (Dispatcher + Handlers), data (ORM + MySQL).
- Dependency Injection via aiogram’s middleware (inject DB session).
- Read‑write splitting for scalability and fault tolerance.
- Modular handlers grouped by domain (user, channels, default).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    TAPI((Telegram Bot API)):::presentation

    %% Bot Core & Dispatcher
    Main["main.py / Dispatcher"]:::application
    Config["config.py"]:::application
    Settings["settings.json"]:::application
    UICommands["bot/ui_commands.py"]:::application

    %% Filters & Middlewares
    Filters["bot/filters/chat_type.py"]:::application
    Middleware["bot/middlewares/database.py"]:::application

    %% Handlers
    subgraph "Handlers" 
        direction TB
        DefBlocks["blocks.py"]:::application
        DefErrors["errors.py"]:::application
        Channels["channels/"]:::application
        Chats["chats/"]:::application
        DeepLink["unhandled.py"]:::application
        Start["start.py"]:::application
    end

    %% FSM
    FSM["bot/states.py"]:::application

    %% Keyboards
    subgraph "Keyboards" 
        direction TB
        Factory["factory.py"]:::application
        Inline["inline.py"]:::application
        Reply["reply.py"]:::application
    end

    %% Database Engine & Router
    subgraph "Database Engine & Router"
        direction TB
        Manager["manager.py"]:::data
        Routing["routing.py"]:::data
    end

    %% ORM Models
    subgraph "ORM Models"
        direction TB
        Base["base.py"]:::data
        DefaultModel["default.py"]:::data
    end

    %% MySQL Cluster
    MySQLMaster[(MySQL Master)]:::db
    MySQLReplica[(MySQL Replica)]:::db

    %% Connections
    TAPI --> Main
    Config --> Main
    Settings --> Main
    UICommands --> Main
    Main --> Filters
    Filters --> Middleware
    Middleware --> DefBlocks
    Middleware --> DefErrors
    Middleware --> Channels
    Middleware --> Chats
    Middleware --> DeepLink
    Middleware --> Start

    DefBlocks --> FSM
    DefErrors --> FSM
    Channels --> FSM
    Chats --> FSM
    DeepLink --> FSM
    Start --> FSM

    FSM --- DefBlocks
    FSM --- DefErrors
    FSM --- Channels
    FSM --- Chats
    FSM --- DeepLink
    FSM --- Start

    DefBlocks --> Factory
    DefBlocks --> Inline
    DefBlocks --> Reply
    DefErrors --> Factory
    DefErrors --> Inline
    DefErrors --> Reply
    Channels --> Factory
    Channels --> Inline
    Channels --> Reply
    Chats --> Factory
    Chats --> Inline
    Chats --> Reply
    DeepLink --> Factory
    DeepLink --> Inline
    DeepLink --> Reply
    Start --> Factory
    Start --> Inline
    Start --> Reply

    Factory --> Main
    Inline --> Main
    Reply --> Main

    DefBlocks --> Routing
    DefErrors --> Routing
    Channels --> Routing
    Chats --> Routing
    DeepLink --> Routing
    Start --> Routing

    Manager --> Routing
    Routing -->|write| MySQLMaster
    Routing -->|read| MySQLReplica

    MySQLMaster --> Routing
    MySQLReplica --> Routing

    Routing --> Main
    Main --> TAPI

    %% Click Events
    click Main "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/main.py"
    click Config "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/config.py"
    click Settings "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/settings.json"
    click UICommands "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/bot/ui_commands.py"
    click Filters "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/bot/filters/chat_type.py"
    click Middleware "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/bot/middlewares/database.py"
    click DefBlocks "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/bot/handlers/default/blocks.py"
    click DefErrors "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/bot/handlers/default/errors.py"
    click Channels "https://github.com/hexdevop/aiogram_sqlalchemy_replication/tree/main/bot/handlers/channels/"
    click Chats "https://github.com/hexdevop/aiogram_sqlalchemy_replication/tree/main/bot/handlers/chats/"
    click DeepLink "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/bot/handlers/user/deep_link/unhandled.py"
    click Start "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/bot/handlers/user/main/start.py"
    click Factory "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/bot/keyboards/factory.py"
    click Inline "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/bot/keyboards/inline.py"
    click Reply "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/bot/keyboards/reply.py"
    click FSM "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/bot/states.py"
    click Manager "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/bot/database/engine/manager.py"
    click Routing "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/bot/database/engine/routing.py"
    click Base "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/bot/database/models/base.py"
    click DefaultModel "https://github.com/hexdevop/aiogram_sqlalchemy_replication/blob/main/bot/database/models/default.py"

    %% Styles
    classDef presentation fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef application fill:#E2F0D9,stroke:#333,stroke-width:1px
    classDef data fill:#FFE6CC,stroke:#333,stroke-width:1px
    classDef db fill:#FFDDAA,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
