💰 Personal Expense Tracker

A full-stack web application to analyze and categorize monthly expenses from bank statements (CSV & PDF) with intelligent auto-categorization.

🎯 Problem Statement

Managing personal finances is challenging when bank statements are just raw transaction data. This app transforms messy CSV exports and PDF bank statements into actionable insights by:

• Automatically categorizing transactions using pattern matching (170+ merchant rules)
• Extracting transactions from PDF bank statements (ICICI, HDFC, SBI, etc.)
• Learning user preferences over time
• Providing clear salary vs. spending analysis

✨ Features

Feature	Description
📤 CSV Upload	Upload any bank statement CSV
📄 PDF Upload	Extract transactions from PDF bank statements
🤖 Auto-Categorization	Rule-based engine with 170+ merchant rules
🧠 Learning System	Remembers user categorizations for future transactions
📊 Dashboard	Visual summary of income, expenses, and balance
✏️ Inline Editing	Change categories with instant save
💵 Credit Tracking	Track money received from others

🛠️ Tech Stack

┌─────────────────────────────────────────────────────────┐
│                      FRONTEND                           │
│  HTML5 • CSS3 • Responsive Design • Dynamic Templates  │
├─────────────────────────────────────────────────────────┤
│                      BACKEND                            │
│  Python 3 • Flask • Pandas • RESTful Routes            │
├─────────────────────────────────────────────────────────┤
│                    DATA LAYER                           │
│  CSV Parsing • PDF Extraction • Regex Matching • JSON  │
└─────────────────────────────────────────────────────────┘

Core Technologies

• Python 3.8+ - Core programming language
• Flask - Lightweight WSGI web framework
• Pandas - Data manipulation and analysis
• pdfplumber - PDF text extraction
• camelot-py - PDF table extraction (stream mode)
• Gunicorn - Production WSGI HTTP server
• HTML5/CSS3 - Responsive UI with modern gradients

🏗️ Architecture

expense-tracker/
├── webapp.py              # Main Flask application (1400+ lines)
│   ├── Routes             # 8 API endpoints
│   ├── Data Processing    # CSV parsing, PDF extraction, categorization
│   └── Template Rendering # Dynamic HTML generation
├── create_sample_pdf.py   # Generate sample PDF for testing
├── test_pdf_processing.py # PDF extraction tests
├── sample_statement.csv   # Sample CSV bank statement
├── user_mappings.json     # Persistent learned mappings (JSON)
├── uploads/               # Temporary file storage (git-ignored)
├── requirements.txt       # Python dependencies
├── Procfile              # Production deployment config
└── README.md

Key Components

1. Auto-Categorization Engine

GLOBAL_RULES = {
    'SWIGGY': 'Food', 'ZOMATO': 'Food', 'HUNGERBOX': 'Food',
    'AMAZON': 'Shopping', 'FLIPKART': 'Shopping', 'MYNTRA': 'Shopping',
    'UBER': 'Transport', 'OLA': 'Transport', 'RAPIDO': 'Transport',
    'ZERODHA': 'Investments', 'GROWW': 'Investments',
    'BOOKMYSHOW': 'Entertainment', 'NETFLIX': 'Entertainment',
    'BIGBASKET': 'Groceries', 'BLINKIT': 'Groceries',
    # 170+ merchant rules across 12 categories
}

2. PDF Extraction Pipeline

• Camelot (stream mode) - Extracts tabular data from PDF bank statements
• pdfplumber (fallback) - Text-based extraction when table detection fails
• Handles multi-row headers, merged columns, and multi-line transactions
• Supports date formats: DD/MM/YYYY, DD-MM-YYYY, DD.MM.YYYY
• Deduplication to handle overlapping page extractions

3. Learning System

• Stores user corrections in JSON
• Prioritizes learned mappings over global rules
• Persists across sessions

4. Smart Detection

• Auto-detects salary (credits > ₹50,000)
• Identifies auto/transport transactions by amount patterns
• Calculates overspending and net balance

🚀 Quick Start

Clone & Run Locally

# Clone the repository
git clone https://github.com/harininaik/expense-tracker.git
cd expense-tracker

# Install dependencies
pip install -r requirements.txt

# Run the application
python webapp.py

# Open in browser
# http://127.0.0.1:5000

📊 API Endpoints

Method	Endpoint	Description
GET	/	Dashboard with expense summary
GET	/transactions	All transactions with inline editing
GET	/mappings	View/edit saved category mappings
GET	/upload	Upload page for new CSV/PDF
POST	/upload	Process uploaded CSV or PDF file
POST	/categorize	Batch save new categorizations
POST	/update_mapping	Update single mapping
GET	/delete_mapping/<name>	Remove a mapping

📁 Supported File Formats

PDF Bank Statements

Upload your bank statement PDF directly — the app extracts transactions automatically.

Supported banks: ICICI, HDFC, SBI, Axis, Kotak, and most Indian banks with tabular PDF statements.

How it works:

1. Camelot (stream mode) detects table structure in the PDF
2. Multi-row headers are scanned and mapped to standard columns
3. Multi-line transactions are merged (UPI/NEFT/IMPS descriptions)
4. Duplicate rows from overlapping pages are removed
5. Falls back to pdfplumber if Camelot finds no tables

CSV Format Guide

Required Format

Your bank statement CSV must have these columns in this order:

Column 1	Column 2	Column 3	Column 4	Column 5	Column 6	Column 7
Date	Date	Description	-	Debit	Credit	Balance

Example CSV File

Date,Date,Description,-,Debit,Credit,Balance
28/01/2026,28/01/2026,UPI/CR/123456789/SALARY/COMPANY NAME/REF123,-,-,93260.00,93260.00
28/01/2026,28/01/2026,UPI/DR/987654321/SWIGGY/SWIGGY/Payment for order,-,450.00,-,92810.00
29/01/2026,29/01/2026,UPI/DR/456789123/AMAZON/Amazon Pay/Shopping,-,1299.00,-,91511.00
29/01/2026,29/01/2026,UPI/DR/789123456/RAPIDO/Rapido/Ride payment,-,85.00,-,91426.00
30/01/2026,30/01/2026,UPI/CR/321654987/FRIEND NAME/Payment received,-,-,500.00,91926.00
30/01/2026,30/01/2026,UPI/DR/654987321/ZEPTO/Zepto/Groceries,-,320.00,-,91606.00

How to Get Your CSV

PhonePe:

1. Open PhonePe → Profile → Transaction History
2. Click "Download Statement" → Select date range
3. Download as CSV

Google Pay:

1. Open Google Pay → Tap profile picture
2. Go to "Transaction history" → Export
3. Download CSV file

Bank Apps (HDFC, ICICI, SBI, etc.):

1. Login to net banking
2. Go to Accounts → Statement
3. Select date range → Download as CSV

Important Notes

• Date format: DD/MM/YYYY (e.g., 28/01/2026)
• Debit = Money spent (outgoing)
• Credit = Money received (incoming)
• Use - for empty debit/credit fields
• Description should contain merchant/person name

📄 See sample_statement.csv for a complete working example!

Compatible with: PhonePe, Google Pay, Paytm, HDFC, ICICI, SBI, Axis Bank, Kotak

🎨 Screenshots

Dashboard View

• Summary Cards - Salary, Spent, Overspent, From Others, Balance
• Category Breakdown - Visual spending by category with percentages
• Credits Section - Money received from others
• Quick Categorize - Dropdowns for uncategorized transactions

Expense Categories

Rent Food Groceries Shopping Transport Entertainment Investments Family Friends Maid/Cook Travel Others

🔧 Configuration

Add Merchant Rules

# webapp.py - GLOBAL_RULES dictionary
GLOBAL_RULES = {
    'NEW_MERCHANT': 'Category',
}

Modify Categories

# webapp.py - CATEGORIES list
CATEGORIES = [
    "Rent", "Food", "NewCategory",
]

Adjust Salary Threshold

# webapp.py - Line 195
salary = df[df['Credit'] > 50000]['Credit'].sum()  # Change 50000

📈 Future Roadmap

• 📊 Monthly comparison charts (Chart.js)
• 🔔 Budget alerts and spending limits
• 📱 Progressive Web App (PWA)
• 🔐 User authentication (Flask-Login)
• 📤 Export to PDF/Excel
• 🏦 Direct bank API integration
• 🏦 Support more bank PDF formats

🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create feature branch (git checkout -b feature/NewFeature)
3. Commit changes (git commit -m 'Add NewFeature')
4. Push to branch (git push origin feature/NewFeature)
5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.

👩‍💻 Author

Harini Naik

---

Built with Python & Flask
Made with ❤️ for better personal finance management

⭐ Star this repo if you found it helpful!