# katotaku879/budget-app architecture

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

- Interactive diagram: https://gitdiagram.com/katotaku879/budget-app
- Repository: https://github.com/katotaku879/budget-app

## Overview

##### Project Type and Purpose
- This is a standalone, full-stack desktop application implemented as a single Python process.
- Purpose: A PyQt5-based household budget management tool with real-time analytics, goal-tracking, and CSV import/backup support.

##### File Structure Analysis
- Top-level files:
- budget_app.py – monolithic entry point containing UI, business logic, data access
- requirements.txt – lists dependencies (PyQt5, pandas, numpy, SQLite3)
- README.md – full architecture and feature description
- 家計簿アプリ起動.bat – Windows launch scripts
- No separate frontend/backend folders; all layers live in one script.

##### README Insights
- Confirms a 4-layer architecture: Presentation (GUI), Business Logic, Data, Analysis Engine.
- Describes MVC pattern with BaseWidget for common UI components.
- Lists 5 main GUI widgets and 5 core database tables in budget.db.

##### Main Components
a. Presentation Layer (PyQt5 GUI)
- Widgets: IncomeExpenseWidget, BreakdownWidget,
MonthlyReportWidget, GoalManagementWidget, SavingsGoalWidget
- BaseWidget common functionality (navigation, styling)
b. Business Logic Layer
- Controllers handling user actions, input validation, goal management
- Real-time calculations via pandas (e.g., update_monthly_expense)
- CSV import & backup scheduler
c. Data Access Layer
- SQLite connector module (CRUD operations, transaction management)
- pandas bridges (read_sql, DataFrame processing)
d. Persistence Layer (SQLite Database)
- budget.db file with tables: expenses, monthly_income, recurring_expenses, category_goals, savings_goals
e. (Optional) Analysis Engine
- Trend computation, AI-powered advice module (future extension)

##### Relationships and Data Flows
- User → GUI widget (slots/signals) → Business Logic
- Business Logic → Data Access (SQL queries, pandas DataFrames) → SQLite
- Data Access → pandas/Numpy processing → Business Logic → GUI updates
- CSV import flow: CSV file → pandas transform → Data Access → SQLite
- Backup flow: SQLite file copy → local backup storage

##### Architectural Patterns and Principles
- Layered (4-layer) architecture: clear separation of concerns
- MVC style: Widgets = View, business-logic methods = Controller, SQLite = Model
- BaseWidget inheritance promotes DRY UI code
- Data normalization in DB, transaction safety in Data Access

##### Key Technologies and Libraries
- Python 3.7+
- PyQt5 (Widgets, Charts)
- SQLite3 (lightweight RDBMS)
- pandas/numpy for in-memory analysis
- shutil & scheduler for backup automation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        IEW["IncomeExpenseWidget"]:::presentation
        BW["BreakdownWidget"]:::presentation
        MRW["MonthlyReportWidget"]:::presentation
        GMW["GoalManagementWidget"]:::presentation
        SGW["SavingsGoalWidget"]:::presentation
        BWd["BaseWidget"]:::presentation
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        Controllers["Controllers (user actions, validation, goal mgmt)"]:::logic
        RealTime["Real-time Analytics (pandas)"]:::logic
        CSVImport["CSV Import Scheduler"]:::logic
        BackupSched["Backup Scheduler"]:::logic
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        direction TB
        SQLiteConn["SQLite Connector (CRUD, transactions)"]:::dataaccess
        PandasBridge["Pandas Bridge (read_sql, DataFrame)"]:::dataaccess
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        DB["budget.db\n(expenses, monthly_income,\nrecurring_expenses,\ncategory_goals,\nsavings_goals)"]:::persistence
    end

    %% Documentation & Config
    subgraph "Project Docs & Config"
        direction TB
        README["README.md"]:::docs
        Req["requirements.txt"]:::docs
        Launch["Launch Script: 家計簿アプリ起動.bat"]:::docs
        Shortcut["Shortcut: 家計簿アプリ起動.bat - ショートカット.lnk"]:::docs
    end

    %% Connections
    IEW -->|signals/slots| Controllers
    BW -->|signals/slots| Controllers
    MRW -->|signals/slots| Controllers
    GMW -->|signals/slots| Controllers
    SGW -->|signals/slots| Controllers
    BWd -->|inheritance| IEW
    BWd -->|inheritance| BW
    BWd -->|inheritance| MRW
    BWd -->|inheritance| GMW
    BWd -->|inheritance| SGW

    Controllers -->|calls| SQLiteConn
    Controllers -->|calls| PandasBridge
    SQLiteConn -->|connects to| DB
    PandasBridge -->|processes DataFrame| Controllers

    CSVImport -->|reads CSV & transforms| PandasBridge
    CSVImport -->|writes data| SQLiteConn
    BackupSched -->|copies DB| DB

    Controllers -->|triggers| RealTime
    RealTime -->|returns analytics| Controllers

    %% Docs links
    README --- Controllers
    Req --- Controllers
    Launch --- Controllers
    Shortcut --- Controllers

    %% Click Events
    click IEW "https://github.com/katotaku879/budget-app/blob/main/budget_app.py"
    click BW "https://github.com/katotaku879/budget-app/blob/main/budget_app.py"
    click MRW "https://github.com/katotaku879/budget-app/blob/main/budget_app.py"
    click GMW "https://github.com/katotaku879/budget-app/blob/main/budget_app.py"
    click SGW "https://github.com/katotaku879/budget-app/blob/main/budget_app.py"
    click BWd "https://github.com/katotaku879/budget-app/blob/main/budget_app.py"
    click Controllers "https://github.com/katotaku879/budget-app/blob/main/budget_app.py"
    click RealTime "https://github.com/katotaku879/budget-app/blob/main/budget_app.py"
    click CSVImport "https://github.com/katotaku879/budget-app/blob/main/budget_app.py"
    click BackupSched "https://github.com/katotaku879/budget-app/blob/main/budget_app.py"
    click SQLiteConn "https://github.com/katotaku879/budget-app/blob/main/budget_app.py"
    click PandasBridge "https://github.com/katotaku879/budget-app/blob/main/budget_app.py"
    click README "https://github.com/katotaku879/budget-app/blob/main/README.md"
    click Req "https://github.com/katotaku879/budget-app/blob/main/requirements.txt"
    click Launch "https://github.com/katotaku879/budget-app/blob/main/家計簿アプリ起動.bat"
    click Shortcut "https://github.com/katotaku879/budget-app/blob/main/家計簿アプリ起動.bat - ショートカット.lnk"

    %% Styles
    classDef presentation fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef logic fill:#d4edda,stroke:#333,stroke-width:1px
    classDef dataaccess fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef persistence fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef docs fill:#f8d7da,stroke:#333,stroke-width:1px
```
