# ravingupta/budgeting architecture

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

- Interactive diagram: https://gitdiagram.com/ravingupta/budgeting
- Repository: https://github.com/ravingupta/budgeting

## Overview

##### Project type and purpose
- This is a lightweight, full-stack, monolithic budgeting web application.
- Purpose: Allow users to upload bank CSV statements, auto-categorize transactions via built-in parsers and ML logic, store everything locally in a database, and present a dashboard UI.

##### File structure
- Top-level scripts:
- main.py – Boots the FastAPI/Uvicorn server
- migration.py – Initializes database schema
- setup.sh / start.sh – Environment and launch scripts
- app/ – FastAPI route definitions (accounts.py, transactions.py, dashboard.py)
- models/ – SQLModel ORM definitions (Account, Category, Transaction, Base)
- parsers/ – CSV parser framework (parser.py) and specific bank parser (scotia.py)
- workers/ – Background analyzer for advanced categorization logic (uses Pandas, Transformers, TensorFlow-Keras)
- scripts/ – Data-feed helpers for seeding accounts/categories
- templates/ – Jinja2 HTML templates (accounts, transactions, dashboard) styled with Tailwind CSS
- config.py & constants/apis.py – Configuration and constant definitions for APIs, file paths, DB connection strings

##### README for additional insights
- Highlights:
- FastAPI + Uvicorn for backend
- SQLModel for local DB
- Pandas + ML stack for transaction categorization
- Jinja2 + Tailwind CSS for frontend
- No external bank APIs—everything runs locally on CSV input.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client"
        direction TB
        BrowserUI["Browser UI"]:::frontend
    end

    %% Server Layer
    subgraph "FastAPI Server"
        direction TB
        Main["main.py"]:::backend
        Config["config.py"]:::backend
        Constants["constants/apis.py"]:::backend

        subgraph "HTTP Routers & Controllers"
            direction TB
            AccountsCtrl["Accounts Controller"]:::api
            TransactionsCtrl["Transactions Controller"]:::api
            DashboardCtrl["Dashboard Controller"]:::api
        end

        subgraph "Business Logic & Processing"
            direction TB
            ParserFramework["Parser Framework"]:::processing
            ScotiaParser["Scotia Parser"]:::processing
            AnalyzerWorker["Analyzer Worker"]:::processing
        end

        subgraph "Data Layer"
            direction TB
            BaseModel["Base Model"]:::model
            AccountModel["Account Model"]:::model
            CategoryModel["Category Model"]:::model
            TransactionModel["Transaction Model"]:::model
        end
    end

    %% Database
    Database["SQLite DB"]:::database

    %% Templates & Static
    subgraph "Presentation Layer"
        direction TB
        LayoutTpl["layout.html"]:::template
        AccountsIndexTpl["accounts/index.html"]:::template
        AccountsDetailsTpl["accounts/details.html"]:::template
        TransactionsTpl["transactions/index.html"]:::template
        DashboardTpl["dashboard.html"]:::template
    end

    %% Scripts
    subgraph "CLI Utilities"
        direction TB
        Migration["migration.py"]:::script
        FeedAccounts["feed_accounts.py"]:::script
        FeedCategories["feed_categories.py"]:::script
        SetupSh["setup.sh"]:::script
        StartSh["start.sh"]:::script
    end

    %% Flow connections
    BrowserUI -->|GET HTML| DashboardCtrl
    BrowserUI -->|GET HTML| AccountsCtrl
    BrowserUI -->|GET HTML| TransactionsCtrl

    AccountsCtrl -->|SQLModel queries| Database
    TransactionsCtrl -->|POST CSV file| ParserFramework
    ParserFramework -->|uses ScotiaParser| ScotiaParser
    ParserFramework -->|normalizes| TransactionModel
    ParserFramework -->|SQL INSERT| Database

    Database -->|polls for new records| AnalyzerWorker
    AnalyzerWorker -->|ML inference| Database

    DashboardCtrl -->|SQLModel queries| Database

    Migration -->|initializes schema| Database
    FeedAccounts -->|insert seed data| Database
    FeedCategories -->|insert seed data| Database

    %% Click events
    click Main "https://github.com/ravingupta/budgeting/blob/main/main.py"
    click AccountsCtrl "https://github.com/ravingupta/budgeting/blob/main/app/accounts.py"
    click TransactionsCtrl "https://github.com/ravingupta/budgeting/blob/main/app/transactions.py"
    click DashboardCtrl "https://github.com/ravingupta/budgeting/blob/main/app/dashboard.py"
    click BaseModel "https://github.com/ravingupta/budgeting/blob/main/models/base.py"
    click AccountModel "https://github.com/ravingupta/budgeting/blob/main/models/account.py"
    click CategoryModel "https://github.com/ravingupta/budgeting/blob/main/models/category.py"
    click TransactionModel "https://github.com/ravingupta/budgeting/blob/main/models/transaction.py"
    click Migration "https://github.com/ravingupta/budgeting/blob/main/migration.py"
    click ParserFramework "https://github.com/ravingupta/budgeting/blob/main/parsers/parser.py"
    click ScotiaParser "https://github.com/ravingupta/budgeting/blob/main/parsers/scotia.py"
    click AnalyzerWorker "https://github.com/ravingupta/budgeting/blob/main/workers/analyzer.py"
    click FeedAccounts "https://github.com/ravingupta/budgeting/blob/main/scripts/feed_accounts.py"
    click FeedCategories "https://github.com/ravingupta/budgeting/blob/main/scripts/feed_categories.py"
    click SetupSh "https://github.com/ravingupta/budgeting/blob/main/setup.sh"
    click StartSh "https://github.com/ravingupta/budgeting/blob/main/start.sh"
    click Config "https://github.com/ravingupta/budgeting/blob/main/config.py"
    click Constants "https://github.com/ravingupta/budgeting/blob/main/constants/apis.py"
    click LayoutTpl "https://github.com/ravingupta/budgeting/blob/main/templates/layout.html"
    click AccountsIndexTpl "https://github.com/ravingupta/budgeting/blob/main/templates/accounts/index.html"
    click AccountsDetailsTpl "https://github.com/ravingupta/budgeting/blob/main/templates/accounts/details.html"
    click TransactionsTpl "https://github.com/ravingupta/budgeting/blob/main/templates/transactions/index.html"
    click DashboardTpl "https://github.com/ravingupta/budgeting/blob/main/templates/dashboard.html"

    %% Styles
    classDef frontend fill:#C3E6FF,stroke:#0B75C9,color:#0B75C9
    classDef backend fill:#D6EAF8,stroke:#2980B9,color:#2980B9
    classDef api fill:#BBDEFB,stroke:#1976D2,color:#1976D2
    classDef processing fill:#FFE0B2,stroke:#EF6C00,color:#E65100
    classDef database fill:#C8E6C9,stroke:#388E3C,color:#2E7D32
    classDef model fill:#E8F5E9,stroke:#43A047,color:#1B5E20
    classDef template fill:#F3E5F5,stroke:#8E24AA,color:#6A1B9A
    classDef script fill:#ECEFF1,stroke:#546E7A,color:#37474F
```
