🧾 Smart Budget Tracker

A full-stack personal finance application that combines PaddleOCR-powered receipt scanning, AI-based categorization, interactive data visualizations, and a financial chatbot — all in a clean, single-page experience.

---

✨ Features

Feature	Description
📱 GPay Screenshot OCR	Upload a Google Pay screenshot — PaddleOCR extracts text, Gemini structures it
🧾 Bill / Receipt Scanner	Upload any receipt image to extract individual line items with prices and categories
💵 Manual Entry	Quick-add cash expenses with vendor, category, date, and description
📊 Visual Dashboard	Pie chart for category breakdown + bar chart for monthly spending trends (Chart.js)
📈 Financial Analysis	Metrics panel showing total spent, average expense, category count, and monthly activity
💬 AI Chatbot	Ask Gemini questions about your spending patterns and get personalized financial insights
📥 CSV Export	Download all expense data as a .csv file
🔐 User Auth	Register / Login with bcrypt-hashed passwords
💰 Budget Setup	Set your monthly salary and spending budget on first sign-up

---

🏗️ Tech Stack

Layer	Technology
Backend (Node.js)	Express.js 5, Node.js v18+
Backend (Python)	FastAPI, Uvicorn
OCR	PaddleOCR 2.7 + PaddlePaddle
AI Categorization	Google Gemini 2.5 Flash (google-genai)
AI Chatbot	Google Gemini 2.5 Flash (@google/generative-ai)
Database	SQLite via better-sqlite3 (WAL mode)
Auth	bcryptjs for password hashing
Frontend	Vanilla HTML / CSS / JavaScript
Charts	Chart.js (CDN)

---

📁 Project Structure

mini-project-final/
├── start.bat              # One-click launcher (Windows) — starts both servers
├── .gitignore
├── README.md
├── UI/                    # Node.js Express server (auth, expenses, chatbot)
│   ├── server.js
│   ├── package.json
│   ├── .env               # Gemini API key (not committed)
│   ├── budget.db          # SQLite database (auto-created, not committed)
│   ├── Login.html
│   ├── Register.html
│   ├── salary_budget.html
│   └── budget.html        # Main dashboard
└── new_ocr/               # Python FastAPI server (PaddleOCR + Gemini categorization)
    ├── api.py             # FastAPI app — receives image, returns structured JSON
    ├── ocr.py             # PaddleOCR text extraction
    ├── ai_categorizer.py  # Gemini 2.5 Flash receipt parser
    ├── requirements.txt
    └── .env               # Gemini API key (not committed)

---

🚀 Getting Started

Prerequisites

• Node.js v18 or higher — download
• Python 3.10 or higher — download
• Google Gemini API Key — get one here

Installation

1. Clone the repository

git clone <repo-url>
cd mini-project-final

2. Install Node.js dependencies

cd UI
npm install
cd ..

3. Set up Python environment

cd new_ocr
python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

pip install -r requirements.txt
cd ..

4. Configure environment

Create a .env file inside both UI/ and new_ocr/:

GEMINI_API_KEY=your_gemini_api_key_here

5. Start the app

On Windows, simply double-click start.bat from the project root. It will:

• Start the Python PaddleOCR server on port 8000 (new window)
• Start the Node.js server on port 3000

Or start manually:

# Terminal 1 — Python OCR service
cd new_ocr
venv\Scripts\activate
python api.py

# Terminal 2 — Node.js server
cd UI
node server.js

6. Open in browser

http://localhost:3000/Login.html

---

🔗 API Endpoints

Node.js (port 3000)

Method	Endpoint	Description
POST	/api/register	Create a new user account
POST	/api/login	Authenticate and log in
PUT	/api/user	Update salary and budget
GET	/api/expenses/:userId	Fetch all expenses for a user
POST	/api/expenses	Add one or more expenses
DELETE	/api/expenses/:id	Delete an expense
POST	/extract	Proxy → Python OCR service
POST	/chat	AI financial chatbot (Gemini)

Python FastAPI (port 8000)

Method	Endpoint	Description
POST	/extract	PaddleOCR + Gemini categorization

---

📂 Database Schema

users
├── id            INTEGER PRIMARY KEY
├── name          TEXT NOT NULL
├── email         TEXT NOT NULL UNIQUE
├── password_hash TEXT NOT NULL
├── salary        REAL DEFAULT 0
└── budget        REAL DEFAULT 0

expenses
├── id          INTEGER PRIMARY KEY
├── user_id     INTEGER (FK → users.id)
├── date        TEXT NOT NULL
├── amount      REAL NOT NULL
├── item        TEXT NOT NULL          -- category (Food, Transport, etc.)
├── vendor      TEXT
├── description TEXT
├── type        TEXT                   -- 'manual' | 'gpay' | 'bill'
└── created_at  TEXT

---

📜 License

This project is licensed under ISC.