Personal Finance Dashboard

A complete full-stack personal finance management application with ML-based categorization, budget tracking, and data visualization.

Features

Backend (Express + TypeScript + SQLite)

CSV Import: Import bank statements from major banks (Chase, Bank of America, Wells Fargo, etc.)
ML-Based Categorization: Automatic transaction categorization using keyword matching and pattern recognition
Transaction CRUD: Full Create, Read, Update, Delete operations
Budget Management: Set spending limits with alerts and tracking
Recurring Transaction Detection: AI-powered detection of subscription patterns
RESTful API: Complete API for all operations

Frontend (React + TypeScript + Tailwind + Recharts)

Dashboard: Overview with key metrics, charts, and alerts
Transaction List: Searchable, filterable transaction management
Category Management: Customizable categories with auto-categorization rules
Budget Tracking: Visual progress tracking with alerts
Data Import/Export: CSV upload with preview and mapping
Charts & Reports: Pie charts, line graphs, bar charts for spending analysis

Tech Stack

Backend

Runtime: Node.js 18+
Framework: Express.js 4.18+
Language: TypeScript 5.3+
Database: SQLite3 with async/await wrapper
File Upload: Multer
CSV Parsing: csv-parser
Unique IDs: uuid
CORS: Enabled for frontend communication

Frontend

Framework: React 18
Language: TypeScript 5.2+
Build Tool: Vite 5.0+
Styling: Tailwind CSS 3.3+
Routing: React Router DOM 6.20+
Charts: Recharts 2.10+
HTTP Client: Axios 1.6+
Icons: Lucide React
Date Formatting: date-fns

Quick Start

Prerequisites

Node.js 18+ installed
npm or yarn package manager

Installation

Clone and enter the project:

cd finance-dashboard

Install backend dependencies:

cd backend
npm install

Install frontend dependencies:

cd ../frontend
npm install

Running the Application

Start the backend (from backend directory):

cd backend
npm run dev

The API will be available at http://localhost:3001

Start the frontend (from frontend directory, in a new terminal):

cd frontend
npm run dev

The app will be available at http://localhost:5173

Open your browser and navigate to http://localhost:5173

Project Structure

finance-dashboard/
 backend/
    src/
       controllers/     # API controllers (transactions, categories, budgets, etc.)
       middleware/      # Express middleware (error handling)
       models/          # Database models (placeholder for future ORM)
       routes/          # API route definitions
       services/        # Business logic (ML categorizer, CSV import)
       types/           # TypeScript type definitions
       utils/           # Utilities (database connection)
    data/                # SQLite database (auto-created)
    uploads/             # Temporary CSV uploads
 frontend/
    src/
       components/      # Reusable React components
       pages/           # Page components (Dashboard, Transactions, etc.)
       services/        # API client and services
       types/           # TypeScript type definitions
       utils/           # Formatters and helpers
    public/              # Static assets
 README.md

API Endpoints

Transactions

Method	Endpoint	Description
GET	`/api/transactions`	List transactions with filters
POST	`/api/transactions`	Create transaction
GET	`/api/transactions/:id`	Get transaction by ID
PUT	`/api/transactions/:id`	Update transaction
DELETE	`/api/transactions/:id`	Delete transaction
POST	`/api/transactions/bulk-delete`	Bulk delete transactions
POST	`/api/transactions/bulk-update-category`	Bulk update category

Budgets

Method	Endpoint	Description
GET	`/api/budgets`	List all budgets
GET	`/api/budgets/alerts`	Get budget alerts
GET	`/api/budgets/summary`	Get budget summary
POST	`/api/budgets`	Create budget
GET	`/api/budgets/:id`	Get budget by ID
PUT	`/api/budgets/:id`	Update budget
DELETE	`/api/budgets/:id`	Delete budget

Dashboard

Method	Endpoint	Description
GET	`/api/dashboard/stats`	Get dashboard statistics
GET	`/api/dashboard/spending-by-category`	Spending breakdown
GET	`/api/dashboard/monthly-trends`	Monthly trends
GET	`/api/dashboard/budget-vs-actual`	Budget comparison
GET	`/api/dashboard/cash-flow`	Cash flow analysis
GET	`/api/dashboard/insights`	AI spending insights
GET	`/api/dashboard/recurring`	Recurring patterns

CSV Import/Export

Method	Endpoint	Description
POST	`/api/csv/upload`	Upload and import CSV
POST	`/api/csv/preview`	Preview CSV data
POST	`/api/csv/detect-format`	Auto-detect CSV format
GET	`/api/csv/template`	Get column mapping template
GET	`/api/csv/export`	Export transactions

ML Categorization

The application uses a rule-based ML system that:

Matches keywords in transaction descriptions
Recognizes patterns for common merchants
Learns from user corrections (adds keywords when you manually categorize)
Detects recurring transactions based on frequency analysis

Default Categories

Category	Color	Type	Keywords
Food & Dining	#EF4444	expense	restaurant, food, grocery, cafe, coffee
Transportation	#F59E0B	expense	gas, uber, lyft, taxi, bus, train
Shopping	#10B981	expense	amazon, walmart, target, store, shop
Entertainment	#8B5CF6	expense	netflix, spotify, movie, game, hulu
Bills & Utilities	#3B82F6	expense	electric, water, internet, phone
Healthcare	#EC4899	expense	pharmacy, doctor, medical, health
Income	#10B981	income	salary, deposit, paycheck, income
Rent/Mortgage	#6366F1	expense	rent, mortgage, housing, apartment
Subscriptions	#14B8A6	expense	subscription, membership, recurring
Travel	#F97316	expense	hotel, flight, airline, booking
Education	#8B5CF6	expense	tuition, course, book, school
Investments	#84CC16	both	investment, stock, dividend, trading
Transfers	#6B7280	both	transfer, venmo, paypal, zelle
Other	#9CA3AF	both	-

CSV Format Guide

Supported Bank Formats

The application supports auto-detection for the following bank CSV formats:

Generic CSV Format

Date,Description,Amount,Type
01/15/2024,Grocery Store,-45.67,expense
01/14/2024,Salary Deposit,3000.00,income

Chase Bank

Transaction Date,Description,Amount,Type
01/15/2024,WHOLEFDS MARKET,-125.43,debit
01/14/2024,DIRECT DEPOSIT,3000.00,credit

Column Mapping:

Date: Transaction Date
Description: Description
Amount: Amount
Type: Type (debit/credit)

Bank of America

Date,Payee,Amount
01/15/2024,NETFLIX.COM,-15.99
01/14/2024,PAYROLL DEPOSIT,3000.00

Column Mapping:

Date: Date
Description: Payee
Amount: Amount

Wells Fargo

Date,Description,Amount
01/15/2024,CHECK #1234,-250.00
01/14/2024,ACH DEPOSIT,3000.00

Citi Bank

Date,Description,Amount,Debit/Credit
01/15/2024,AMAZON.COM,-45.67,DEBIT
01/14/2024,DIRECT DEPOSIT,3000.00,CREDIT

American Express

Date,Description,Amount
01/15/2024,UBER *EATS,-28.50
01/14/2024,REFUND ADJUSTMENT,50.00

CSV Import Requirements

Required Columns:

Date - Transaction date (supports MM/DD/YYYY, DD/MM/YYYY, YYYY-MM-DD)
Description - Transaction description/payee/merchant
Amount - Transaction amount (supports negative numbers, parentheses for negative)

Optional Columns:

Type - Transaction type (income/expense, debit/credit, deposit/withdrawal)
Account Name - Source account name
Category - Pre-defined category (if not provided, auto-categorization is used)

Amount Format Support

The parser handles various amount formats:

$45.67 - Currency symbol
(45.67) - Parentheses for negative
-45.67 - Negative sign
45.67 CR - Credit suffix
45.67 DR - Debit suffix
1,234.56 - Thousand separators

Date Format Support

The parser auto-detects these date formats:

MM/DD/YYYY (US format)
DD/MM/YYYY (European format)
YYYY-MM-DD (ISO format)
MM-DD-YYYY

Development

Backend Development

cd backend
npm run dev        # Start with hot reload (ts-node-dev)
npm run build      # Build for production
npm run lint       # Run ESLint
npm run test       # Run tests (if configured)

Frontend Development

cd frontend
npm run dev        # Start Vite dev server
npm run build      # Build for production
npm run lint       # Run ESLint
npm run preview    # Preview production build

Environment Variables

Backend (.env file)

PORT=3001
NODE_ENV=development
FRONTEND_URL=http://localhost:5173

Frontend (.env file)

VITE_API_URL=http://localhost:3001/api

Screenshots

The dashboard includes:

Overview Cards: Income, Expenses, Balance, Transaction Count
Spending Chart: Pie chart showing spending by category
Trends Chart: Line chart of monthly income vs expenses
Budget Alerts: Visual warnings when approaching limits
Recent Transactions: Quick view of latest activity
Upcoming Bills: Detected recurring payments

Database Schema

Tables

transactions

Column	Type	Description
id	TEXT PRIMARY KEY	Unique identifier
date	TEXT	Transaction date (YYYY-MM-DD)
description	TEXT	Transaction description
amount	REAL	Transaction amount (positive)
category_id	TEXT	Foreign key to categories
type	TEXT	income/expense
account_name	TEXT	Source account
notes	TEXT	Additional notes
created_at	DATETIME	Creation timestamp
updated_at	DATETIME	Last update timestamp

budgets

Column	Type	Description
id	TEXT PRIMARY KEY	Unique identifier
category_id	TEXT	Foreign key to categories
amount	REAL	Budget amount
period	TEXT	monthly/yearly
start_date	TEXT	Budget start date
end_date	TEXT	Budget end date (optional)
alert_threshold	REAL	Alert percentage (default 80)
created_at	DATETIME	Creation timestamp
updated_at	DATETIME	Last update timestamp

Method	Endpoint	Description
GET	`/api/categories`	List all categories
POST	`/api/categories`	Create category
GET	`/api/categories/:id`	Get category by ID
PUT	`/api/categories/:id`	Update category
DELETE	`/api/categories/:id`	Delete category
GET	`/api/categories/:id/stats`	Get category statistics
POST	`/api/categories/:id/keywords`	Add keyword for auto-categorization
DELETE	`/api/categories/:id/keywords/:keyword`	Remove keyword

Column	Type	Description
id	TEXT PRIMARY KEY	Unique identifier
name	TEXT	Category name
color	TEXT	Hex color code
type	TEXT	income/expense/both
keywords	TEXT	JSON array of keywords
created_at	DATETIME	Creation timestamp
updated_at	DATETIME	Last update timestamp

Latest commit

History

Folders and files

Repository files navigation