# damirtag/dodobot architecture

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

- Interactive diagram: https://gitdiagram.com/damirtag/dodobot
- Repository: https://github.com/damirtag/dodobot

## Overview

##### Project Type & Purpose
- This is a Telegram bot designed to retrieve and display information about Dodo Pizza locations. It leverages the aiogram framework to interface with Telegram, uses PostgreSQL as its database (working with AsyncPG and SQLAlchemy), and fetches data from the Dodo IS API via aiohttp. Additional features include caching (aiocache) and scheduled tasks (APScheduler) for tasks such as revenue checking.

##### Analyzing the File Structure
- The project is split primarily across a top-level main.py and a src folder.
- Inside src, you have:
- The database module (under src/database) that contains base connection code, enums, models (for example, User), and actions (reports, stats, user) to perform common database operations.
- The handlers folder divided into subfolders for admin, command, inline, and keyboard. These clearly abstract how different types of user interactions (commands, inline queries, custom keyboards) are managed.
- A models directory (src/models) separate from the database module, which may define additional business models.
- A scheduler directory indicates periodic tasks (e.g., revenue_checker) likely driven by APScheduler.
- The services folder contains modules such as dodo_api to interface with external APIs.
- Additional misc utilities, decorators, UI elements, and general utilities (logger, formatting, pagination, etc.) that support the core functionality.

- Main Components to Represent:
a. Telegram Bot Interface (aiogram): Indicates the entry point (main.py) that instantiates the bot and routes incoming messages.
b. Handlers Module: Breakout into submodules:
- Admin Handlers (src/handlers/admin): Managing administrative commands.
- Command Handlers (src/handlers/command): Processes standard bot commands (favorite, revenue, search, stop_report).
- Inline & Keyboard Handlers (src/handlers/inline and src/handlers/keyboard): Managing user inputs via inline query and dynamic keyboards.
c. Database Module: Summarize components such as:
- Database Connection/Base (src/database/base.py).
- Data Models & enums (src/database/models and src/database/enums).
- Data Actions (inside src/database/actions) that encapsulate queries and operations.
d. API Service: Represent the service layer (src/services/dodo_api) that handles remote API calls to the Dodo IS API.
e. Scheduler Component: APScheduler based tasks (src/scheduler/revenue_checker) that execute periodic tasks like revenue checking.
f. Utility & Miscellaneous Libraries: Logger, formatting, UI text management (src/misc, src/utils); decorators enforcing admin and new user validations.

- Relationships & Data Flow:
- The Telegram Bot (via aiogram) receives messages and passes them to the relevant handlers.
- Handlers then interact with the Database Module for any CRUD operations (for users, reports, statistics) or with the API Service to fetch external data.
- Scheduled Tasks can trigger API calls and database updates, running asynchronously.
- Utility and Decorator modules are cross-cutting components supporting core functionalities such as logging and request validation.

##### Architectural Patterns & Design Principles
- Modularity: The project is well-structured into discreet modules (database, handlers, scheduler, services, utils).
- Separation of Concerns: Each module (e.g., API, database, command handling) is independently maintained.
- Asynchronous Operations: Use of asyncio-friendly libraries (aiogram, aiohttp, AsyncPG, etc.) implies non-blocking design.
- Integration via Abstraction: For example, database actions are centralized under one file tree, enabling uniform interfacing with both SQLAlchemy and AsyncPG.

## Diagram (Mermaid)

```mermaid
graph TD
    A["Telegram Bot Interface (aiogram)"]
    
    subgraph "Handlers Layer"
        H1["Admin Handlers"]
        H2["Command Handlers"]
        H3["Inline Handlers"]
        H4["Keyboard Handlers"]
    end

    subgraph "Database Module"
        D1["Database Connection/Base"]
        D2["Database Models"]
        D3["Database Enums"]
        D4["Database Actions"]
    end

    B["API Service (Dodo IS API)"]
    S["Scheduler Component (APScheduler)"]

    subgraph "Utilities & Business Models"
        U1["Decorators"]
        U2["Miscellaneous Utilities & Logger"]
        M1["Additional Business Models"]
    end

    %% Core Flows
    A -->|"routes"| H1
    A -->|"routes"| H2
    A -->|"routes"| H3
    A -->|"routes"| H4

    H1 -->|"CRUD"| D4
    H2 -->|"CRUD"| D4
    H3 -->|"CRUD"| D4
    H4 -->|"CRUD"| D4

    H1 -->|"externalCall"| B
    H2 -->|"externalCall"| B
    H3 -->|"externalCall"| B
    H4 -->|"externalCall"| B

    D1 -->|"defines"| D2
    D1 -->|"defines"| D3

    S -->|"triggers"| B
    S -->|"updates"| D4

    U1 ---|"support"| A
    U1 ---|"support"| H1
    U2 ---|"support"| D1
    U2 ---|"support"| B

    %% Styling Classes
    class A bot;
    class H1,H2,H3,H4 handler;
    class D1,D2,D3,D4 db;
    class B api;
    class S scheduler;
    class U1,U2 util;
    class M1 business;

    %% Class Definitions with Colors
    classDef bot fill:#ffe6f2,stroke:#cc0066,stroke-width:2px;
    classDef handler fill:#e6f7ff,stroke:#0066cc,stroke-width:2px;
    classDef db fill:#e6ffe6,stroke:#339933,stroke-width:2px;
    classDef api fill:#fff0e6,stroke:#ff8000,stroke-width:2px;
    classDef scheduler fill:#fff9cc,stroke:#d4af37,stroke-width:2px;
    classDef util fill:#e6f9ff,stroke:#0099cc,stroke-width:2px;
    classDef business fill:#ffe6e6,stroke:#cc0000,stroke-width:2px;

    %% Click Events
    click A "https://github.com/damirtag/dodobot/blob/main/main.py"
    click H1 "https://github.com/damirtag/dodobot/tree/main/src/handlers/admin"
    click H2 "https://github.com/damirtag/dodobot/tree/main/src/handlers/command"
    click H3 "https://github.com/damirtag/dodobot/tree/main/src/handlers/inline"
    click H4 "https://github.com/damirtag/dodobot/tree/main/src/handlers/keyboard"
    click D1 "https://github.com/damirtag/dodobot/blob/main/src/database/base.py"
    click D2 "https://github.com/damirtag/dodobot/blob/main/src/database/models/User.py"
    click D3 "https://github.com/damirtag/dodobot/blob/main/src/database/enums/basic.py"
    click D4 "https://github.com/damirtag/dodobot/tree/main/src/database/actions"
    click B "https://github.com/damirtag/dodobot/blob/main/src/services/dodo_api.py"
    click S "https://github.com/damirtag/dodobot/blob/main/src/scheduler/revenue_checker.py"
    click U1 "https://github.com/damirtag/dodobot/tree/main/src/misc/decorators"
    click U2 "https://github.com/damirtag/dodobot/blob/main/src/utils/logger.py"
    click M1 "https://github.com/damirtag/dodobot/tree/main/src/models"
```
