TraceBack

TraceBack helps you understand exactly what caused you to overspend — and what to do about it. By securely connecting to your bank account via Plaid, TraceBack provides detailed financial analysis including spending patterns, category breakdowns, and actionable insights into your transaction history.

🔗 Live Demo: https://trace-back.netlify.app/

---

Features

• 🏦 Secure Bank Connection - Connect your bank account safely via Plaid
• 📊 Spending Analysis - Comprehensive breakdown of expenses by category
• 📈 Weekly Trace - Visualize spending patterns across weeks
• 🎯 Overspend Detection - Identify which categories and transactions caused overspending
• 📅 Multi-Month Analysis - Compare spending patterns across different time periods
• 🔍 Category Drilldown - Deep dive into specific spending categories
• 💡 Counterfactual Analysis - Understand what-if scenarios for better budgeting
• 📌 Shapley Attribution - ML-powered feature importance analysis for spending insights

---

Tech Stack

Frontend

• React 19.2.4 - Modern UI library
• Vite 8.0.4 - Fast build tool and dev server
• Tailwind CSS 3.4.19 - Utility-first CSS framework
• Recharts 3.8.1 - Composable charting library
• Plaid Link - Secure bank account authentication

Backend

• FastAPI 0.135.3 - Modern Python web framework
• Plaid Python SDK 39.0.0 - Bank account integration
• Python 3.11+ - Core runtime

Infrastructure

• Frontend Deployment: Netlify
• Backend Deployment: Render
• Authentication: Plaid Link (OAuth-based)
• Data Storage: Plaid API (transactions stored in Plaid, access tokens securely cached locally)

---

Architecture

How It Works

1. Bank Connection Flow

   • User clicks "Link Bank Account" on the frontend
   • Frontend requests a link token from the backend
   • Plaid Link widget opens securely
   • User selects bank and authenticates
   • Frontend receives public_token from Plaid Link
   • Frontend sends public_token to backend for exchange
   • Backend exchanges for access_token (stored securely)

2. Transaction Analysis Flow

   • User selects a month to analyze
   • Frontend requests analysis data from backend
   • Backend fetches transactions from Plaid API
   • Backend performs overspend analysis:
     • Categorizes transactions using Plaid's personal finance categories
     • Calculates spending by category
     • Applies counterfactual and Shapley attribution analysis
     • Identifies overspend drivers
   • Backend returns analysis results to frontend
   • Frontend visualizes data with interactive charts

Data Flow Diagram

Frontend (React/Vite)
    ↓
Backend (FastAPI)
    ↓
Plaid API
    ↓
User's Bank

---

Local Setup

Prerequisites

• Python 3.11+
• Node.js 18+
• Plaid account (sandbox keys available at plaid.com)

Backend Setup

1. Navigate to backend directory

   cd backend

2. Create and activate virtual environment

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Create .env file with Plaid credentials:

   PLAID_CLIENT_ID=your_client_id
   PLAID_SECRET=your_secret
   PLAID_ENVIRONMENT=sandbox

5. Run backend server

   PYTHONPATH=$(pwd) ./venv/bin/uvicorn main:app --reload --port 8000

   Backend runs at http://localhost:8000

Frontend Setup

1. Navigate to frontend directory

   cd frontend

2. Install dependencies

   npm install

3. Create .env.local file (for local API connection):

   VITE_API_URL=http://localhost:8000/api

4. Run development server

   npm run dev

   Frontend runs at http://localhost:5173

Access the App

Open http://localhost:5173 in your browser and start analyzing!

---

Deployment

Environment Variables

Frontend (Netlify)

• VITE_API_URL: Your Render backend URL with /api path
  • Example: https://traceback-backend-xxxx.onrender.com/api

Backend (Render)

• PLAID_CLIENT_ID: Your Plaid client ID
• PLAID_SECRET: Your Plaid secret
• PLAID_ENVIRONMENT: sandbox or production

Build & Deploy Commands

Frontend Build

cd frontend && npm run build

Backend Start Command (for Render)

uvicorn main:app --host 0.0.0.0 --port $PORT

---

Project Structure

traceback/
├── backend/
│   ├── main.py                 # FastAPI application & routes
│   ├── plaid_client.py         # Plaid SDK integration
│   ├── analysis.py             # Financial analysis logic
│   ├── requirements.txt         # Python dependencies
│   └── .env                    # Plaid credentials (not in repo)
├── frontend/
│   ├── src/
│   │   ├── main.jsx            # React entry point
│   │   ├── App.jsx             # Main app component
│   │   ├── components/
│   │   │   ├── PlaidAuth.jsx   # Plaid Link integration
│   │   │   ├── Dashboard.jsx   # Main analysis dashboard
│   │   │   ├── MetricCards.jsx # KPI cards
│   │   │   ├── WeeklyTrace.jsx # Weekly spending chart
│   │   │   ├── CategoryDrilldown.jsx  # Category breakdown
│   │   │   └── ...
│   │   └── pages/
│   │       ├── Home.jsx        # Landing page
│   │       └── Dashboard.jsx   # Analysis pages
│   ├── package.json            # Node dependencies
│   ├── vite.config.js          # Vite configuration
│   └── index.html              # HTML entry point
└── README.md

---

Key API Endpoints

Plaid Integration

• POST /api/link-token - Create Plaid Link token
• POST /api/exchange-token - Exchange public token for access token

Analysis

• GET /api/analyze/:user_id?month=<offset> - Get spending analysis
  • month=0: Current month
  • month=1: Last month
  • month=2: Two months ago, etc.

---

Development Notes

CORS Configuration

The backend CORS middleware allows:

• Localhost (development): http://localhost:5173, http://localhost:3000
• Production: https://trace-back.netlify.app, https://*.netlify.app

Token Storage

• Access tokens are stored in /tmp/plaid_tokens.json on the backend
• Each user's token is accessed by their user_id
• Tokens are never sent to frontend

Transaction Normalization

Plaid's personal_finance_category tags are mapped to user-friendly category names for better UX.

---

Performance Optimizations

• Frontend: Vite's code splitting and lazy loading
• Backend: Caching of Plaid responses to reduce API calls
• Charts: Recharts for efficient data visualization

---

Security

• 🔒 Bank credentials never shared with frontend (Plaid Link handles auth)
• 🔐 Access tokens stored securely on backend only
• ✅ CORS properly configured to prevent unauthorized access
• 🛡️ Environment variables for sensitive configuration

---

Troubleshooting

"Failed to create link token" Error

• Verify PLAID_CLIENT_ID and PLAID_SECRET in backend .env
• Ensure backend is running and accessible
• For Netlify: Confirm VITE_API_URL includes /api path

"Analysis failed" Error

• Check that bank account is properly linked
• Verify Plaid sandbox credentials are valid
• Ensure backend has valid access token for the user

CORS Errors

• Update backend main.py CORS origins if deploying to new domain
• Clear browser cache and reload

---

Future Enhancements

• Budget goal tracking and alerts
• Recurring transaction detection
• Spending forecasting with ML
• Multi-account support
• Mobile app version

---

License

MIT

---

Support

For issues or questions, please open an issue in the repository.