# koolhackerz/schedule-assistant-bot architecture

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

- Interactive diagram: https://gitdiagram.com/koolhackerz/schedule-assistant-bot
- Repository: https://github.com/koolhackerz/schedule-assistant-bot

## Overview

##### Identify the Project Type and Purpose

**Project Type:**
Schedule Assistant Bot is a **Telegram bot** designed to help university students manage their class schedules and receive daily inspirational quotes. It is a **bot-based application** leveraging Telegram's platform for interaction.

**Purpose:**
The bot provides interactive schedule access, automated notifications, daily quotes, sticker search functionality, and admin features for managing user interactions and broadcasts. It aims to simplify schedule management and add motivational content to students' daily routines.

##### Analyze the File Structure

**Top-Level Directories and Files:**
- `.github/workflows/deploy.yml`: CI/CD pipeline configuration for deployment.
- `src/`: Contains the source code.
- `bot/`: Core bot functionality.
- `__init__.py`
- `config.py`: Configuration settings.
- `main.py`: Entry point for the bot.
- `quotes.py`: Handles daily quotes feature.
- `schedule_sending.py`: Manages automated schedule notifications.
- `telegram_bot.py`: Integrates with Telegram API.
- `utils.py`: Utility functions.
- `data/`: Stores data files.
- `assignments.json`, `localization.json`: Configuration and localization data.
- `audio/voice.m4a`: Audio resources.
- `schedules/`: JSON files for Russian and Ukrainian schedules.
- `database/`: Database interactions.
- `__init__.py`
- `db.py`: Database setup and management.
- `handlers/`: Request handlers for different bot commands.
- Various handler files like `admin_handlers.py`, `assignments_handlers.py`, etc.

**Configuration and Dependency Management:**
- `pyproject.toml`: Dependency management using Poetry.
- `.gitignore`: Specifies files to ignore in version control.
- `ChangeLog.md` and `README.md`: Documentation files.

**Patterns and Architectural Choices:**
- **Modular Structure:** Separation of concerns with distinct directories for bot logic, data, database, and handlers.
- **MVC-Like Pattern:** Handlers act as controllers managing interactions between the bot (view) and data/database (model).
- **Configuration Management:** Centralized in `config.py` and environment variables for flexibility.

##### Examine the README for Additional Insights

**Architecture and Dependencies:**
- Built with **Python 3.12** and managed with **Poetry**.
- Utilizes an **SQLite database** for data storage.
- **Loguru** for logging.

**Key Components:**
- **Bot Functionality:** Core features like schedule viewing, notifications, quotes, and sticker search.
- **Admin Interface:** For sending broadcast messages.
- **Data Management:** JSON files for schedules and localization, SQLite for persistent storage.
- **Customization:** Allows editing schedules, quotes, and adding new languages.

**a. Identify the Main Components:**
- **Telegram Client:** Users interact through Telegram.
- **Telegram Bot API:** Facilitates communication between the bot and Telegram.
- **Bot Core (`src/bot/main.py`):** Entry point handling bot initialization.
- **Handlers (`src/handlers/`):** Manage different user commands and interactions.
- **Database (`src/database/db.py`):** Manages data storage and retrieval.
- **Data Layer (`src/data/`):** Stores schedules, localization, and audio files.
- **Utility Modules (`src/bot/utils.py`):** Helper functions.
- **Configuration (`src/bot/config.py`):** Manages environment settings.
- **Logging (`logs/`):** Stores application logs.

**b. Determine Relationships and Interactions:**
- **Telegram Client ↔ Telegram Bot API ↔ Bot Core:** Users send commands via Telegram, which are processed by the Bot Core.
- **Bot Core ↔ Handlers ↔ Database/Data Layer:** Handlers process specific commands, interact with the Database or Data Layer as needed.
- **Bot Core ↔ Utilities:** Utilizes utility functions for common tasks.
- **Bot Core ↔ Configuration:** Reads configurations for operation parameters.
- **Bot Core ↔ Logging:** Logs activities and errors for monitoring.

**c. Highlight Architectural Patterns or Design Principles:**
- **Modularity:** Clear separation between different functionalities (handlers, database, utilities).
- **Separation of Concerns:** Each component has a distinct responsibility, enhancing maintainability.
- **Scalability:** Modular handlers allow for easy addition of new features.
- **Configuration Management:** Centralized configuration for flexibility across environments.

**d. Include Relevant Technologies, Frameworks, or Libraries:**
- **Python 3.12:** Core programming language.
- **Poetry:** Dependency management and packaging.
- **SQLite:** Lightweight database solution.
- **Loguru:** Logging library for monitoring.
- **Telegram Bot API:** For interacting with Telegram.
- **JSON:** Data format for schedules and localization.

##### Elements

- **Clear Labels for Each Component:** Name each part of the system clearly (e.g., "Telegram Client", "Bot Core").
- User commands flowing from Telegram Client to Bot API.
- Bot API sending data to Bot Core.
- Bot Core interacting with Handlers and Database.
- Handlers accessing Data Files.

##### Emphasize Detailed and Essential Architectural Elements

- **Component Granularity:** Ensure each major module (e.g., `handlers`, `database`, `utils`) is represented as separate entities.
- **Configuration and Environment Management:** Include how configurations are loaded and used by different components.
- **Logging and Monitoring:** Represent the logging mechanism and its integration with other components.

##### Final Recommendations

- **Detail Each Layer:** Break down into specific modules and their interactions.
- **Use Visual Hierarchy:** Clearly differentiate between core functionalities and supporting modules.
- **Incorporate Technologies:** Label components with the technologies they use (e.g., Python, SQLite).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Global entities
    User["Telegram Client"]:::user
    API["Telegram Bot API"]:::user

    %% Application Logic Layer
    subgraph "Application Logic"
        BotCore["Bot Core"]:::logic
        TeleBotAPI["Telegram Bot API Integration"]:::logic
        Handlers["Handlers"]:::logic
        Quotes["Quotes Feature"]:::logic
        Schedule["Schedule Notifications"]:::logic
        Utils["Utility Functions"]:::utility
        Config["Configuration Management"]:::config
    end

    %% Data Management Layer
    subgraph "Data Management"
        Database[(SQLite Database)]:::database
        DataLayer["Data Layer"]:::data
        Assignments["Assignments Data"]:::data
        Localization["Localization Data"]:::data
        RusSchedule["Russian Schedule"]:::data
        UkrSchedule["Ukrainian Schedule"]:::data
        Audio["Audio Resources"]:::data
    end

    %% Connections
    User -->|sends commands| API
    API -->|communicates with| BotCore
    BotCore -->|integrates via| TeleBotAPI
    BotCore -->|uses| Handlers
    Handlers -->|accesses| Database
    Handlers -->|accesses| DataLayer
    DataLayer --> Assignments
    DataLayer --> Localization
    DataLayer --> RusSchedule
    DataLayer --> UkrSchedule
    DataLayer --> Audio
    BotCore -->|uses| Utils
    BotCore -->|reads| Config
    BotCore -->|accesses| Quotes
    BotCore -->|manages| Schedule

    %% Click Events
    click BotCore "https://github.com/koolhackerz/schedule-assistant-bot/blob/main/src/bot/main.py"
    click TeleBotAPI "https://github.com/koolhackerz/schedule-assistant-bot/blob/main/src/bot/telegram_bot.py"
    click Config "https://github.com/koolhackerz/schedule-assistant-bot/blob/main/src/bot/config.py"
    click Quotes "https://github.com/koolhackerz/schedule-assistant-bot/blob/main/src/bot/quotes.py"
    click Schedule "https://github.com/koolhackerz/schedule-assistant-bot/blob/main/src/bot/schedule_sending.py"
    click Utils "https://github.com/koolhackerz/schedule-assistant-bot/blob/main/src/bot/utils.py"
    click Handlers "https://github.com/koolhackerz/schedule-assistant-bot/tree/main/src/handlers/"
    click Database "https://github.com/koolhackerz/schedule-assistant-bot/blob/main/src/database/db.py"
    click DataLayer "https://github.com/koolhackerz/schedule-assistant-bot/tree/main/src/data/"
    click Assignments "https://github.com/koolhackerz/schedule-assistant-bot/blob/main/src/data/assignments.json"
    click Localization "https://github.com/koolhackerz/schedule-assistant-bot/blob/main/src/data/localization.json"
    click RusSchedule "https://github.com/koolhackerz/schedule-assistant-bot/blob/main/src/data/schedules/rus_schedule.json"
    click UkrSchedule "https://github.com/koolhackerz/schedule-assistant-bot/blob/main/src/data/schedules/ukr_schedule.json"
    click Audio "https://github.com/koolhackerz/schedule-assistant-bot/blob/main/src/data/audio/voice.m4a"

    %% Styles
    classDef user fill:#1f78b4,stroke:#000,stroke-width:1px;
    classDef logic fill:#33a02c,stroke:#000,stroke-width:1px;
    classDef database fill:#a6cee3,stroke:#000,stroke-width:1px;
    classDef data fill:#fb9a99,stroke:#000,stroke-width:1px;
    classDef utility fill:#cab2d6,stroke:#000,stroke-width:1px;
    classDef config fill:#ff7f00,stroke:#000,stroke-width:1px;

    class User,API user
    class BotCore,TeleBotAPI,Handlers,Quotes,Schedule logic
    class Database database
    class DataLayer,Assignments,Localization,RusSchedule,UkrSchedule,Audio data
    class Utils utility
    class Config config
```
