# emilastanov/ast-manager-bot architecture

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

- Interactive diagram: https://gitdiagram.com/emilastanov/ast-manager-bot
- Repository: https://github.com/emilastanov/ast-manager-bot

## Overview

This project is a Telegram bot (named ast-manager-bot) that automates order management, user interactions, and price calculations for an embroidery store. It leverages PostgreSQL for data persistence (with database migrations managed by Alembic) and integrates with Google Sheets to pull external data. With Docker and CI/CD (via GitHub Actions) already in place, the project is designed for reliable deployment and testing.

##### Main Components
- Telegram Bot Interface:
- Entry Point: main.py – where the bot starts up.
- Command Handlers: Located in the commands/ directory (e.g., start, users), which handle incoming bot commands.
- Button Handlers and Inline Query Handlers: Found in button_handlers/ and inline_query_handlers/ directories. These manage user interactions such as pagination and inline queries (like calculating price).
- Business Logic & Core:
- Core business operations like those encapsulated in core/ (module loaders, etc.) and utility functions in utils/ to format messages or handle pagination.
- Data Persistence:
- Models: Using SQLAlchemy models in models/ (for instance, User model) that define the database schema.
- Data Access Layer: CRUD operations in the crud/ directory (e.g., finding or creating users, implementing pagination for users’ lists).
- Migrations: The migrations/ directory with Alembic scripts to manage database versioning.
- External Services:
- Services: Integration with PostgreSQL (services/db.py) and Google Sheets (services/google_sheets/) to fetch, update, or aggregate external data.
- Text Templates:
- Located in texts/ – these provide user-facing messages and templates for the Telegram bot.
- Testing & Deployment Tools:
- tests/: Contains unit tests built with PyTest.
- Dockerfile: For containerizing the bot.
- CI/CD configurations: GitHub Actions workflows found in .github/workflows/ (ci-cd.yml) for building, testing, and deploying the application.

##### Out the Relationships and Interactions
- User Interaction Layer: Telegram users interact with the bot through the Telegram client.
- Communication Flow:
- Incoming messages/commands are received by main.py, which dispatches them to the appropriate handlers (commands/, button_handlers/, inline_query_handlers/).
- The handlers invoke functions in the business logic layer (crud/, core/, and services/), where the core operations are carried out.
- For any state changes or persistence, the bot makes calls to the services that interact with the PostgreSQL database (via models/ and migrations/) or external sources like Google Sheets.
- Response Generation: Once operations are complete, texts/ and utils/ are utilized to format and send back responses to the user.

##### Architectural Patterns & Technologies
- The project uses a modular architecture, segmenting responsibilities into distinct directories.
- Separation of concerns is evident: the division between request-handling (commands, button and inline query handlers) and business logic (CRUD, core) ensures clear interaction boundaries.
- It also employs external services integration for cohesive functionality—direct connections to PostgreSQL and Google Sheets.
- Technologies include Python (with modules and packages), SQLAlchemy for ORM, Alembic for migrations, Docker for containerization, and GitHub Actions for automation.

## Diagram (Mermaid)

```mermaid
graph TD
    A["Telegram Client (User Interface)"]:::ui
    B["Bot Entry Point (main.py)"]:::entry

    subgraph "Handlers Layer"
        C["Command Handlers"]:::handler
        D["Button Handlers"]:::handler
        E["Inline Query Handlers"]:::handler
    end

    subgraph "Business Logic"
        F["Core Business Logic"]:::logic
        G["Utilities"]:::logic
        H["CRUD Operations"]:::logic
    end

    subgraph "Data Persistence"
        I["Data Models"]:::data
        J["Database Migrations"]:::data
        K["PostgreSQL Integration"]:::data
    end

    subgraph "External Services"
        L["Google Sheets Integration"]:::external
        M["Text Templates"]:::external
    end

    subgraph "Deployment & Testing"
        N["Testing Suite"]:::deploy
        O["Docker"]:::deploy
        P["CI/CD Pipeline"]:::deploy
        Q["Environment Configuration"]:::deploy
    end

    A --> B
    B --> C
    B --> D
    B --> E

    C --> F
    D --> F
    E --> F

    F --> G
    F --> H
    H -->|"ORM/SQLAlchemy"| I
    I -->|"Alembic"| J
    J --> K

    F --> L
    F --> M
    M -->|"Response"| A

    Q -->|"LoadConfig"| B

    N --> P
    P --> O

    click B "https://github.com/emilastanov/ast-manager-bot/blob/main/main.py"
    click C "https://github.com/emilastanov/ast-manager-bot/tree/main/commands/"
    click D "https://github.com/emilastanov/ast-manager-bot/tree/main/button_handlers/"
    click E "https://github.com/emilastanov/ast-manager-bot/tree/main/inline_query_handlers/"
    click F "https://github.com/emilastanov/ast-manager-bot/blob/main/core/module_loader.py"
    click G "https://github.com/emilastanov/ast-manager-bot/blob/main/utils/format_user_list_message.py"
    click H "https://github.com/emilastanov/ast-manager-bot/blob/main/crud/find_or_create_user.py"
    click I "https://github.com/emilastanov/ast-manager-bot/blob/main/models/User.py"
    click J "https://github.com/emilastanov/ast-manager-bot/tree/main/migrations/"
    click K "https://github.com/emilastanov/ast-manager-bot/blob/main/services/db.py"
    click L "https://github.com/emilastanov/ast-manager-bot/blob/main/services/google_sheets/api.py"
    click M "https://github.com/emilastanov/ast-manager-bot/blob/main/texts/hello.py"
    click N "https://github.com/emilastanov/ast-manager-bot/tree/main/tests/"
    click O "https://github.com/emilastanov/ast-manager-bot/tree/main/Dockerfile"
    click P "https://github.com/emilastanov/ast-manager-bot/blob/main/.github/workflows/ci-cd.yml"
    click Q "https://github.com/emilastanov/ast-manager-bot/blob/main/.env.example"

    classDef ui fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef entry fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef handler fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef logic fill:#f8bbd0,stroke:#880e4f,stroke-width:2px;
    classDef data fill:#ffe0b2,stroke:#e65100,stroke-width:2px;
    classDef external fill:#d1c4e9,stroke:#4a148c,stroke-width:2px;
    classDef deploy fill:#fff9c4,stroke:#f57f17,stroke-width:2px;
```
