💼 Budgetly — Premium Local-First Personal Budget Tracker & OCR Receipt Manager

A modern, highly aesthetic, offline-first personal finance and budget tracking desktop application built with Electron, React 18, Vite, and SQLite. Budgetly streamlines receipt ingestion through manual drag-and-drop or an autonomous background Telegram bot daemon, processes documents with offline mock OCR pipelines, and visualizes your financial health on a sleek, interactive dashboard.

---

🌟 Key Features

• 🔄 Dual Ingestion Pipeline:
  • Manual Drag-and-Drop: Drag photos or PDFs of receipt slips directly onto the dashboard to scan.
  • Telegram Bot Ingestion: Snap pictures of physical bills on your phone when out and about, and send them to your private bot; the app automatically pulls, downloads, and processes them.
• 👁️ Automated OCR Segmenter:
  • Offline document-parsing algorithm that simulates value extraction (vendor, amount, date, and suggested category).
  • Animated laser scan overlays on receipt uploads with a satisfying physical stamp animation upon confirmation.
• 🪙 Refill Widget & Flying Coin Animation:
  • Seeded daily-use "Purse" wallet that can be instantly refilled from a primary Bank account.
  • Staggered coin elements flying across the dashboard to make transferring funds feel tactile and premium.
• 🔥 Allowance Gauge & Streaks:
  • Circular SVG daily allowance spending gauge reflecting remaining funds.
  • Gamified streak trackers checking how many consecutive days you stay under your daily limits.
• 📊 Ledger, Budgets & Analytics:
  • Separate views for a searchable transaction ledger, rollover category-level budgets, and time-series trend lines.
• ⌨️ Premium Desktop Mechanics:
  • Custom frameless title bar and tray icon integration with "minimize to tray" window management.
  • Global keyboard shortcuts (Ctrl+Shift+B for Quick Log) and a spotlight command palette (Ctrl+K) for keyboard-only navigation.
• 💾 Local-First SQLite & Auto Backups:
  • Source of truth stored locally in SQLite (budgetly.db) using high-performance better-sqlite3.
  • App automatically triggers safety rolling backups (maintaining the last 7 sessions) upon boot.
• 📄 One-Page PDF Report Export:
  • Tailored @media print CSS rules formatting app contents into clean investor-style print summaries, omitting navigational bars.

---

🏗️ System Architecture & Data Ingestion Flow

The sequence diagram below displays the dual receipt processing ingestion pathways (Telegram & Drag-and-Drop) feeding into the exact same database transaction ledger:

sequenceDiagram
    actor User as User (Desk / Phone)
    participant TG as Telegram Bot
    participant Main as Electron Main Process
    participant DB as SQLite Local Engine
    participant UI as React Renderer UI

    Note over User, TG: Ingestion via Phone
    User->>TG: Send receipt photo/document
    TG->>Main: Background long-poll download
    Main->>DB: Ingest raw bill draft (unpaid)
    Main->>UI: IPC emit (bill:new-scan)
    
    Note over User, UI: Ingestion via Desktop
    User->>UI: Drag & Drop receipt file
    
    Note over UI, DB: Joint Data Extraction Pipeline
    UI->>UI: Trigger laser scan-sweep animation
    UI->>UI: Render editable extracted data card
    User->>UI: Click "Confirm & Deduct"
    UI->>UI: Trigger spring-loaded "PAID" stamp
    UI->>Main: IPC save transaction details
    Main->>DB: Commit Ledger Transaction
    Main->>DB: Update Bill status to 'paid'
    Main->>UI: Sync account balances & budgets

Loading

---

📁 Repository Structure

budgetly/
├── electron/                   # Electron Main Process source files
│   ├── db/
│   │   ├── database.js         # SQLite connection setup, schemas & seeds
│   │   └── ipc-handlers.js     # DB CRUD operations & analytical bridges
│   ├── telegram/
│   │   └── bot.js              # Telegram Bot API daemon & download listener
│   ├── main.js                 # App lifecycle, tray menus & global shortcuts
│   ├── preload.js              # Secure contextBridge API mappings
│   └── recurring.js            # Recurring transactions validator cron
│
├── src/                        # React Frontend (Vite + TypeScript/JS)
│   ├── components/
│   │   ├── charts/             # Donut, Bar & Trend visual gauges
│   │   ├── layout/             # Frameless TitleBar, Sidebar & command palette
│   │   └── ui/                 # Modals, inputs, toggles & select buttons
│   ├── lib/
│   │   ├── animations.js       # Framer Motion transitions configuration
│   │   └── utils.js            # Currency & date formatting helpers
│   ├── pages/
│   │   ├── Dashboard.jsx       # Overview, streaks & quick purse refill
│   │   ├── Transactions.jsx    # Searchable list & manual ledger log
│   │   ├── Budgets.jsx         # Target limit caps & rollover sliders
│   │   ├── Bills.jsx           # Receipts gallery with OCR review cards
│   │   ├── Goals.jsx           # Target SVG progression circles
│   │   ├── Analytics.jsx       # Ranked segment charts & spending trend lines
│   │   └── Settings.jsx        # Modes, currencies, database paths & Telegram bot tests
│   ├── store/
│   │   ├── useAppStore.js      # Global state for settings, accounts & categories
│   │   └── useTransactionStore.js # Ledger states & transactional parameters
│   ├── App.jsx                 # App routes and dynamic theme-switching listeners
│   ├── index.css               # Base theme styles, custom scrollbars & print rules
│   └── main.jsx                # React DOM mount point
│
├── assets/                     # Application icons & logo assets
├── release/                    # Unpacked standalone binaries output directory
├── package.json                # Project script manifests & dependencies
└── tailwind.config.js          # Design typography tokens & custom color scales

---

⚙️ Mathematical Model: Color-Coded Budget Thresholds

The application monitors category budgets using a dynamic percentage spent ratio, converting raw spending logs into warning states (Green → Yellow → Red):

1. Progress Ratio Formula

The budget consumption ratio ($R_{spent}$) for any category $c$ in month $m$ is defined as:

$$R_{spent} = \left( \frac{\sum E_c}{\text{Limit}_c} \right) \times 100$$

Where:

• $\sum E_c$ is the sum of expense transactions logged for category $c$ in the current month.
• $\text{Limit}_c$ is the maximum cap specified by the user.

2. Alert Threshold Mapping

The UI dynamically updates CSS variables and colors based on $R_{spent}$:

Spent Ratio ($R_{spent}$)	UI Warning State	Color Code	Animation
$< 80%$	Clear / Healthy	Green (#4ADE80)	Static
$80% \text{ to } 99%$	Limit Warning	Yellow (#FBBF24)	Pulses slowly
$\ge 100%$	Limit Exceeded	Red (#F87171)	Flash alert warning bar

---

🚀 Quick Setup & Installation

Prerequisites

• Node.js 18+ & npm
• Google Chrome (for Selenium-based browser components, if running collectors)

1. Installation

Clone the repository and install all dependencies:

npm install

2. Running in Development

Start the concurrent dev servers (Vite client + Electron shell):

npm run dev

3. Packaging Standalone Binaries

Compile Vite assets and build a Windows unpacked executable directory:

npm run dist

The packaged standalone application will be built inside: 👉 release/win-unpacked/Budgetly.exe

---

🔗 IPC Integration API Reference

The secure IPC bridge (window.api) exposes clean, asynchronous API categories:

1. Telegram Service

• window.api.telegram.getStatus() - Returns whether the bot daemon is currently 'active' or 'inactive'.
• window.api.telegram.testConnection(token, chatId) - Launches a temporary test bot instance and pushes a verification message to confirm connection.
• window.api.telegram.restartBot() - Stops active long-polling instances and restarts the daemon with updated credentials.

2. Receipts Storage

• window.api.db.getBills(filters) - Fetches scanned files with optional status filters ('paid' | 'unpaid').
• window.api.db.addBill(data) - Saves a new receipt slip attachment.
• window.api.db.updateBill(id, data) - Modifies fields or links receipt entries to committed ledger transaction IDs.

3. App Controls

• window.api.window.minimize() / maximize() / close() - Operates native chrome windows for the frameless custom title bar.

---

Developed with ❤️ using Electron, React 18, TailwindCSS, and SQLite.