BudgetPe 💰

AI-Powered Expense Tracking via SMS Classification

Track your spending automatically. Your bank sends SMS → We classify it → You see insights.

✨ What's Fixed & Working ✅

✅ Complete end-to-end SMS classification flow ✅ Backend properly stores messages with ML classification ✅ ML Model with intelligent 3-level classification hierarchy ✅ SMS App captures and sends message data correctly ✅ Frontend displays classified expenses with reports ✅ Comprehensive documentation and setup guides

🚀 Quick Start (5 Minutes)

Prerequisites

Node.js 18+
Python 3.8+
MongoDB (local or Atlas)

Run All Services

# Terminal 1: Backend
cd Backend && npm install && npm run dev

# Terminal 2: ML Model
cd "ML model" && python -m venv venv && source venv/Scripts/activate
pip install -r requirements.txt && python app.py

# Terminal 3: Frontend
cd frontend && npm install && npm run dev

# Terminal 4: SMS App (Android)
cd smsApp && npm install && npx expo start

Then:

Open http://localhost:5173
Register/Login
Open SMS App on phone
Send a bank SMS
See it appear in dashboard instantly! ⚡

📱 The Flow

📲 Bank SMS arrives on phone
   ↓ (app polls every 3 sec)
📱 SMS App captures SMS + sender info
   ↓
🤖 ML Model classifies → Food/Travel/Shopping/Others
   ↓
💾 Backend stores in MongoDB with user association
   ↓
🌐 Frontend fetches and displays with analysis
   ↓
📊 User clicks "Generate Report" → See insights & chart

📚 Documentation Guide

Document	Purpose	Read Time
QUICKSTART.md	Get running in 5 minutes	2 min
SETUP.md	Complete setup & troubleshooting	10 min
ARCHITECTURE.md	System design & data flow diagrams	15 min
INTEGRATION_CHECKLIST.md	Verify everything works	5 min
FIX_SUMMARY.md	What was fixed & why	5 min

👉 START HERE: QUICKSTART.md

🏗️ Project Structure

BudgetPe/
├── Backend/                    # Node.js + Express API (port 5000)
│   ├── models/                 # MongoDB schemas
│   ├── controllers/            # Route handlers
│   ├── routes/                 # API endpoints
│   ├── middleware/             # Auth, validation, errors
│   ├── validators/             # Request validation
│   ├── config/                 # Database config
│   └── .env                    # Configuration
│
├── frontend/                   # React + Vite (port 5173)
│   ├── src/
│   │   ├── routes/            # Pages (Dashboard, Login, etc)
│   │   ├── components/        # Reusable UI components
│   │   ├── context/           # Theme context
│   │   ├── utils/             # API & auth utilities
│   │   └── App.jsx
│   └── .env
│
├── smsApp/                     # React Native + Expo (Android)
│   ├── app/                   # Screens & navigation
│   ├── components/            # Reusable components
│   ├── context/              # Auth context
│   ├── lib/                  # API integration
│   └── lib/api.ts            # Backend/ML API calls
│
├── ML model/                   # Python (port 5001)
│   ├── app.py                # Flask API server
│   ├── model.py              # ML model loading
│   ├── pipeline.py           # Classification pipeline
│   ├── utils.py              # Utilities
│   ├── train.py              # Model training script
│   ├── data/                 # Model & training data
│   └── requirements.txt
│
└── Documentation/
    ├── QUICKSTART.md         # Quick reference
    ├── SETUP.md             # Detailed setup
    ├── ARCHITECTURE.md      # System architecture
    ├── INTEGRATION_CHECKLIST.md
    └── FIX_SUMMARY.md

🎯 Classification Logic (How It Works)

3-Level Hierarchy (Smart & Reliable)

🥇 Level 1: Rule-Based Classification (Instant & Fast)

Checks for known merchant keywords
Food: Swiggy, Zomato, Eats, Food, Restaurant
Travel: Uber, Ola, Rapido, Taxi, Cab, Auto, Travel
Shopping: Amazon, Flipkart, Myntra, eBay, Shop, Store
Returns immediately if match found

🥈 Level 2: ML Model (If Rule Failed - Most Accurate)

Uses trained LogisticRegression model
Analyzes:
- Merchant name (TF-IDF vectorized)
- Transaction amount
- Time of transaction (hour)
Trained on bank SMS dataset
Returns prediction

🥉 Level 3: Fallback Heuristics (Always Works)

If ML model unavailable or unsure
Uses amount + time patterns:
- ₹ ≤ 300 AND 6-11 PM → Food
- ₹ 50-500 → Travel
- ₹ > 500 → Shopping
- Otherwise → Others

Result: Reliable classification even if ML model fails! ✅

💾 What Gets Stored

User

{
  _id: ObjectId,
  name: "Mukul",
  email: "mukul@example.com",
  phoneNumber: "9876543210",
  password: "hashed_with_bcrypt",
  createdAt: Date,
  updatedAt: Date
}

Message (What ML Model Classifies)

{
  _id: ObjectId,
  user: ObjectId,              // Linked to user
  originalText: "Debited Rs. 500 to Swiggy...",  // Raw SMS
  category: "food",            // ML classification
  amount: 500,                 // Extracted amount
  receiver: "Swiggy",          // Merchant name
  date: Date,                  // Transaction time
  confidence: 1.0,             // Classification confidence
  createdAt: Date,
  updatedAt: Date
}

🔐 Security Features

✅ Passwords hashed with bcrypt (12 rounds)
✅ JWT Tokens for stateless authentication (7 day expiry)
✅ User Isolation - Each user sees only their messages
✅ Token Verification on all protected endpoints
✅ CORS configured for web and mobile
✅ Environment Variables for secrets (not hardcoded)
✅ Input Validation on all requests

✨ Features & Capabilities

Currently Working ✅ (Phase 1)

Coming Soon 🚀 (Phase 2)

🔧 Tech Stack

Layer	Technology
Frontend	React 18, Vite, Tailwind CSS, React Router
Backend	Node.js, Express, MongoDB, JWT, bcryptjs
Mobile	React Native, Expo, TypeScript
ML/AI	Python 3.8+, Flask, scikit-learn, Pandas
Deployment	Docker (ready), AWS/Heroku compatible

⚙️ Configuration Files

Backend `.env`

# Server
PORT=5000
NODE_ENV=development

# Database
MONGO_URI=mongodb+srv://user:pass@cluster.mongodb.net/budgetpe

# Authentication
JWT_SECRET=your_secret_key_here_change_in_prod
JWT_EXPIRES_IN=7d

# CORS
CLIENT_URL=http://localhost:5173

Frontend `.env`

VITE_API_URL=http://localhost:5000/api
VITE_ML_URL=http://localhost:5001

ML Model (app.py)

Flask server runs on port 5001
Accessible to Backend and SMS App on same network

🆘 Troubleshooting Quick Links

Issue	Solution
SMS App can't connect	Check same WiFi + update IP in `smsApp/lib/api.ts`
ML Model errors	Run `pip install -r requirements.txt` again
Backend won't start	Check MongoDB running or update `MONGO_URI` in `.env`
No messages in dashboard	Login again, check backend health endpoint
Port already in use	Change PORT in `.env` or kill existing process

Full troubleshooting: See SETUP.md

📊 API Endpoints

Authentication

POST /api/auth/register    - Register new user
POST /api/auth/login       - Login (returns JWT token)
GET  /api/auth/me          - Get current user (protected)
POST /api/auth/logout      - Logout

Messages

GET  /api/messages         - Get all user messages (protected)
POST /api/messages         - Save classified message (protected)

Health

GET  /api/health           - Backend health check
GET  /                      - ML Model health check (port 5001)

🧪 Testing the Flow

Manual End-to-End Test

Start all services (see Quick Start section)
Register on Frontend (http://localhost:5173)
Login on SMS App with same credentials
Send/Receive bank SMS on Android phone
Check Dashboard - message appears instantly
Verify Classification - category, amount, merchant correct
Generate Report - click on any category card
View Insights - see breakdown chart and AI insights

Expected Timeline

SMS received → 3 seconds → App detects
App calls ML model → 1 second → Classified
Sends to backend → 1 second → Stored
Frontend polls → Next fetch → Displays
Total: ~5-10 seconds from SMS receipt to dashboard

📈 Performance & Scalability

Component	Capacity	Optimization
Backend	1000s reqs/sec	Node.js + clustering ready
ML Model	100s classifications/sec	Can be horizontally scaled
Database	Millions of records	MongoDB with indexing on userId, date
Frontend	Instant rendering	React optimization, virtualization ready

🚀 Deployment Ready

The project is production-ready for Phase 1:

✅ Error handling
✅ Input validation
✅ Authentication/Authorization
✅ Data isolation
✅ Configuration via environment variables
✅ Docker-ready structure

Pre-deployment checklist:

📝 Development Notes

Adding New Categories

Update Message enum in Backend/models/Message.js
Add validation in Backend/validators/messageValidator.js
Add keywords in ML model/pipeline.py
Add color in Frontend Dashboard.jsx
Retrain model: python ML\ model/train.py

Retraining ML Model

cd "ML model"
# Update data/dataset.csv with new training data
python train.py
# Restart Flask server
python app.py

🎓 Learning Path

Want to understand the project?

Read: FIX_SUMMARY.md - What was done
Read: ARCHITECTURE.md - How it works
Read: SETUP.md - Complete details
Explore: Source code with inline comments

Want to extend it?

Review: ML model classification logic
Add: New expense categories
Integrate: Gemini API for insights
Deploy: To cloud platform

📞 Support & Help

Quick start help: QUICKSTART.md
Setup help: SETUP.md
Architecture questions: ARCHITECTURE.md
What was changed: FIX_SUMMARY.md
Verify everything works: INTEGRATION_CHECKLIST.md

📄 License

MIT License - Free to use and modify!

🎉 Ready?

👉 START WITH QUICKSTART.md

Get the app running in 5 minutes!

Built with ❤️ for expense tracking | Powered by AI | Secured by JWT

npm install
npm run dev

Backend runs at http://localhost:5000

2. Frontend

cd frontend
npm install
npm run dev

Frontend runs at http://localhost:5173

Latest commit

History

Folders and files

Repository files navigation