# steelball-debug/expense-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/steelball-debug/expense-tracker
- Repository: https://github.com/steelball-debug/expense-tracker

## Overview

##### Project type and purpose
- This is a desktop application (“Koin – Expense Tracker App”) written in Python, using CustomTkinter for the GUI.
- It provides personal finance tracking, multi-user support, and offline data storage (JSON).

##### File structure
- Entry Point: main.py
- GUI Modules (Views & Controllers):
- Scripts/Dashboard.py
- Scripts/Heatmap.py
- Scripts/Tabular_view.py
- Scripts/Settings.py
- Utilities: Scripts/Utilities.py (shared helper functions)
- Local Data Storage:
- Scripts/Cache.json (categories, users, lookup dicts)
- Scripts/Transactions.json (expense/income records)
- Dependencies: requirements.txt (Python libraries, including CustomTkinter, matplotlib, etc.)

##### Architecture from README
- Modular “feature-per-file” design.
- JSON files act as the persistent Model.
- CustomTkinter components render the View; main.py orchestrates startup.

##### Main components
a. Frontend (GUI Layer)
- CustomTkinter Application (main.py)
- Dashboard View (Dashboard.py)
- Heatmap View (Heatmap.py)
- Tabular View (Tabular_view.py)
- Settings View (Settings.py)
b. Business Logic Layer
- Utilities Module (Utilities.py)
- Data Validation, Formatting, Category Management
c. Data Layer (Model)
- Local JSON Store (Cache.json, Transactions.json)
d. Assets
e. External Dependencies
- Python Standard Library
- Third-party libs: CustomTkinter, matplotlib, pandas (if used), etc.

##### Relationships & interactions
- main.py initializes the CustomTkinter app → loads the Utilities module → loads Cache.json into memory.
- User interactions in any View module → call functions in Utilities.py → read/write to JSON files.
- Visualization modules (Heatmap, Dashboard) query Transactions.json, build charts (matplotlib), and render via CustomTkinter.
- Settings module updates Cache.json (e.g., add/remove categories or users).
- Tabular view reads Transactions.json for tables, allows edits via Utilities.

##### Architectural patterns & principles
- MVC-style separation:
- Model: JSON files + Utilities for data access
- View: CustomTkinter widgets in each script
- Controller: main.py dispatches commands, views call Utilities
- Modular design: each feature in its own script for maintainability
- Offline-first local storage → no external DB or network dependency

##### Detail requirements
- Clear component names: e.g., “Dashboard.py (View)”
- Arrowheads showing direction of data flow & control

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% GUI Layer
    subgraph "GUI Layer"
        Main["main.py\n(CustomTkinter App)"]:::code
        Dash["Dashboard.py\n(View)"]:::code
        Heat["Heatmap.py\n(View)"]:::code
        Table["Tabular_view.py\n(View)"]:::code
        Set["Settings.py\n(View)"]:::code
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        Util["Utilities.py\n(Business Logic)"]:::code
    end

    %% Data Layer
    subgraph "Data Layer"
        Cache[(Cache.json)]:::data
        Trans[(Transactions.json)]:::data
    end

    %% Assets
    Assets["Assets\n(Icons, Images, Themes)"]:::asset

    %% External Dependencies
    subgraph "External Dependencies"
        Ext["requirements.txt"]:::external
    end

    %% Connections
    Main -->|"load Utilities"| Util
    Main -->|"load cache"| Cache
    Main -->|"show Dashboard"| Dash

    Dash -->|"uses Utilities"| Util
    Heat -->|"uses Utilities"| Util
    Table -->|"uses Utilities"| Util
    Set -->|"uses Utilities"| Util

    Util -->|"read/write"| Cache
    Util -->|"read/write"| Trans

    Dash -->|"fetch for chart"| Trans
    Heat -->|"fetch for chart"| Trans
    Table -->|"fetch for table"| Trans
    Set -->|"update categories"| Cache

    Ext -.-> Main

    %% Click Events
    click Main "https://github.com/steelball-debug/expense-tracker/blob/master/main.py"
    click Dash "https://github.com/steelball-debug/expense-tracker/blob/master/Scripts/Dashboard.py"
    click Heat "https://github.com/steelball-debug/expense-tracker/blob/master/Scripts/Heatmap.py"
    click Table "https://github.com/steelball-debug/expense-tracker/blob/master/Scripts/Tabular_view.py"
    click Set "https://github.com/steelball-debug/expense-tracker/blob/master/Scripts/Settings.py"
    click Util "https://github.com/steelball-debug/expense-tracker/blob/master/Scripts/Utilities.py"
    click Cache "https://github.com/steelball-debug/expense-tracker/blob/master/Scripts/Cache.json"
    click Trans "https://github.com/steelball-debug/expense-tracker/blob/master/Scripts/Transactions.json"
    click Assets "https://github.com/steelball-debug/expense-tracker/tree/master/Assets/"
    click Ext "https://github.com/steelball-debug/expense-tracker/blob/master/requirements.txt"

    %% Styles
    classDef code fill:#D0E6FF,stroke:#1E3A8A,stroke-width:1px
    classDef data fill:#D1FAE5,stroke:#065F46,stroke-width:1px
    classDef asset fill:#FEF3C7,stroke:#92400E,stroke-width:1px
    classDef external fill:#F3F4F6,stroke:#6B7280,stroke-dasharray: 5 5,stroke-width:1px
```
