Real-Time Spending Coach

HackPrinceton project - AI-powered spending tracker that helps users distinguish between NEED and WANT purchases through iMessage interactions.

System Architecture

User makes purchase → Backend receives transaction → Sends iMessage asking "NEED or WANT?"
→ User replies via text → System learns patterns → Predicts future spending → Shows yearly savings

Quick Start

1. Install Dependencies

# Backend
cd backend
npm install

# Frontend
cd frontend
npm install

2. Configure Environment

Create backend/.env:

PORT=3001
USER_PHONE_NUMBER=+12533683150
DATABASE_PATH=./database.db

3. Start Services

# Terminal 1 - Start Backend
cd backend
npm start

# Terminal 2 - Start Frontend
cd frontend
npm run dev

Access:

• Backend API: http://localhost:3001
• Frontend Dashboard: http://localhost:5174

Features

Backend (/backend)

• Express API - REST endpoints for transactions, classifications, predictions
• SQLite Database - Stores transactions, user classifications, merchant predictions
• iMessage Integration - Sends questions and watches for replies using @photon-ai/imessage-kit
• Prediction Engine - Calculates spending patterns and yearly savings

Frontend (/frontend)

• React Dashboard - Real-time transaction feed
• Statistics - Total spent, needs vs wants breakdown
• Predictions Table - AI-predicted future purchases with savings calculations
• Classification UI - Buttons to classify transactions as NEED or WANT

Database Schema

transactions

• Transaction details from purchases
• Links to classifications

classifications

• User's NEED/WANT decisions
• Timestamps and confidence scores

predictions

• Per-merchant predictions
• Average amounts, purchase frequency
• Next purchase date estimates
• Yearly savings if switched to NEED

API Endpoints

GET  /api/dashboard           # Get all data (transactions, stats, predictions)
POST /api/transactions        # Create new transaction (triggers iMessage)
POST /api/classify/:id        # Classify transaction as NEED or WANT
GET  /api/predictions         # Get spending predictions

iMessage Integration

Setup (macOS only)

1. Open System Settings → Privacy & Security → Full Disk Access
2. Add your Terminal app
3. Open Messages.app and sign in with Apple ID
4. Verify iMessage is enabled (Messages → Settings → iMessage)

How It Works

When a transaction is created:

1. Backend sends iMessage via AppleScript
2. User receives: "You bought [item] for $[amount]. Was this a NEED or WANT?"
3. User replies with "NEED" or "WANT"
4. Backend watches Messages database for reply
5. Classification is stored and predictions update

Fallback: If iMessage unavailable, use the web UI to classify transactions.

Demo Flow

1. Add transaction via frontend form (e.g., "Starbucks, Latte, $7.25")
2. Backend logs show: Sent iMessage to +12533683150...
3. Click NEED or WANT button to classify
4. Add more purchases from same merchant
5. Watch predictions calculate yearly savings

Tech Stack

• Backend: Node.js, Express, SQLite, better-sqlite3
• Frontend: React, TypeScript, Vite
• iMessage: @photon-ai/imessage-kit, AppleScript
• Database: SQLite3

Troubleshooting

iMessage not sending:

• Ensure Messages.app is running and signed into iMessage
• Check Terminal has Full Disk Access permission
• Test manually in Messages.app first

Database errors:

• Delete backend/database.db and restart backend (recreates tables)

Port conflicts:

• Backend uses 3001, frontend uses 5173/5174
• Change PORT in .env if needed

Project Structure

hackprinceton/
├── backend/
│   ├── src/
│   │   ├── server.js              # Express server
│   │   ├── database.js            # SQLite operations
│   │   ├── routes/api.js          # API endpoints
│   │   └── services/
│   │       ├── imessageService.js # iMessage sending/watching
│   │       └── predictionService.js # Spending predictions
│   ├── .env                       # Configuration
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── App.tsx               # Main dashboard component
│   │   └── services/api.ts       # Backend API client
│   └── package.json
└── README.md                      # This file

Future Enhancements

• Integrate Knot API for real bank transaction data
• Add Claude AI for automatic classification suggestions
• Support multiple users
• Mobile app for better UX
• Export reports and analytics