# onazart/budget_mono architecture

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

- Interactive diagram: https://gitdiagram.com/onazart/budget_mono
- Repository: https://github.com/onazart/budget_mono

## Overview

##### Project type and purpose
- This is a Python‐based Telegram bot (“budget_govern_bot”) for tracking and reporting daily spending via Monobank.
- Core use case: users send commands or receive scheduled messages; bot fetches transaction data from Monobank, stores it in MongoDB, computes statistics and generates plots, then sends updates back to users.

##### File structure
- Top‐level files:
- Procfile – indicates deployment (e.g., Heroku).
- setup.py, requirements.txt – packaging and dependencies.
- config.ini – tokens, database credentials, scheduling parameters.
- bot_evening_state.py, bot_stat_finance.py, steps_in_bot.py – Telegram handlers and state machine.
- mono.py – Monobank API client.
- data.py, data/…json – data models, categories lookup.
- plot/plots.py – plotting routines (charts for spendings).
- additional_tools.py – shared utilities.
##### README for additional insights
- Technologies: Python, pyTelegramBot, MongoDB.
- Only works with Monobank.

##### Detailed capture of essential architecture
- Related Python modules under a “Telegram Bot Application” boundary.
- Config.ini feeding credentials into both Monobank client and MongoDB connector.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Users and Services
    Users["Telegram Users"]:::external
    TelegramAPI["Telegram Bot API"]:::external
    MonobankAPI["Monobank REST API"]:::external

    %% Configuration and Deployment
    Config["config.ini"]:::config
    Procfile["Procfile"]:::infra
    Setup["setup.py"]:::infra
    Req["requirements.txt"]:::infra

    %% Database
    MongoDB[(MongoDB)]:::db

    %% Bot Application Boundary
    subgraph "Telegram Bot Application"
        direction TB

        %% API Layer - Handlers
        subgraph "API Layer"
            direction TB
            EveningHandler["Evening State Handler"]:::handler
            StatisticsHandler["Statistics Commands Handler"]:::handler
            StepsHandler["Conversation Steps Handler"]:::handler
        end

        %% Service Layer - Business Logic
        subgraph "Service Layer"
            direction TB
            MonoClient["Monobank API Client"]:::service
            DataModel["Data Models & Persistence"]:::service
            CategoryData["Category Lookup Data"]:::service
            PlotEngine["Plotting Engine"]:::service
            Utils["Shared Utilities"]:::service
        end

        %% Scheduler
        Scheduler(["Scheduler"]):::scheduler
    end

    %% Flows
    Users -->|"/start, /stats, etc."| TelegramAPI
    TelegramAPI -->|deliver messages| EveningHandler
    TelegramAPI -->|deliver messages| StatisticsHandler
    TelegramAPI -->|deliver messages| StepsHandler

    EveningHandler -->|uses| Scheduler
    Scheduler -->|triggers| EveningHandler

    EveningHandler -->|fetch transactions| MonoClient
    StatisticsHandler -->|fetch transactions| MonoClient
    StepsHandler -->|fetch transactions| MonoClient

    MonoClient -->|write/read| DataModel
    DataModel -->|store/read| MongoDB

    DataModel -->|load| CategoryData
    Utils -->|assist| MonoClient
    Utils -->|assist| DataModel
    Utils -->|assist| PlotEngine

    StatisticsHandler -->|generate plots| PlotEngine
    PlotEngine -->|uses| DataModel

    StatisticsHandler -->|send images/text| TelegramAPI
    EveningHandler -->|send summary| TelegramAPI
    StepsHandler -->|send replies| TelegramAPI

    Config -->|provides creds| MonoClient
    Config -->|provides URI| DataModel
    Config -->|provides schedule| Scheduler

    %% External interactions
    MonoClient -->|HTTP requests| MonobankAPI

    %% Click Events
    click EveningHandler "https://github.com/onazart/budget_mono/blob/main/bot_evening_state.py"
    click StatisticsHandler "https://github.com/onazart/budget_mono/blob/main/bot_stat_finance.py"
    click StepsHandler "https://github.com/onazart/budget_mono/blob/main/steps_in_bot.py"
    click MonoClient "https://github.com/onazart/budget_mono/blob/main/mono.py"
    click DataModel "https://github.com/onazart/budget_mono/blob/main/data.py"
    click CategoryData "https://github.com/onazart/budget_mono/blob/main/data/categories.json"
    click CategoryData "https://github.com/onazart/budget_mono/blob/main/data/wider_categories.json"
    click PlotEngine "https://github.com/onazart/budget_mono/blob/main/plot/plots.py"
    click Utils "https://github.com/onazart/budget_mono/blob/main/additional_tools.py"
    click Config "https://github.com/onazart/budget_mono/blob/main/config.ini"
    click Procfile "https://github.com/onazart/budget_mono/tree/main/Procfile"
    click Setup "https://github.com/onazart/budget_mono/blob/main/setup.py"
    click Req "https://github.com/onazart/budget_mono/blob/main/requirements.txt"

    %% Styles
    classDef external fill:#FFE4B5,stroke:#D2691E,color:#000000;
    classDef handler fill:#E6E6FA,stroke:#9370DB,color:#000000;
    classDef service fill:#F0FFF0,stroke:#32CD32,color:#000000;
    classDef db fill:#FFFACD,stroke:#FFD700,color:#000000;
    classDef config fill:#F5F5F5,stroke:#A9A9A9,color:#000000;
    classDef infra fill:#F0F8FF,stroke:#4682B4,color:#000000;
    classDef scheduler fill:#FFF0F5,stroke:#FF69B4,color:#000000;
```
