Small project to replicate a spreadsheet used to manage my finances - tied in with plaid
- Vue 55.6%
- TypeScript 41.6%
- CSS 0.9%
- Dockerfile 0.7%
- Makefile 0.5%
- Other 0.7%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| client | ||
| docs | ||
| references | ||
| scripts | ||
| server | ||
| .env.example | ||
| .gitignore | ||
| CLAUDE.md | ||
| deploy.md | ||
| docker-compose.local.yml | ||
| docker-compose.yml | ||
| Makefile | ||
| README.md | ||
Finance Tracker
A personal finance tracking web app built around bi-weekly pay periods. Transactions are pulled automatically from bank accounts and credit cards via Plaid. The interface mirrors a spreadsheet: dense, keyboard-friendly, black and white.
Stack
- Backend: Node.js + TypeScript + Express
- Frontend: Vue 3 (Composition API) + Vite
- Database: PostgreSQL
- Bank data: Plaid API
Features
- Connect multiple bank accounts and credit cards via Plaid
- Bi-weekly pay period view with Net Start, Carry Over, and budget tracking
- Rule-based automatic transaction categorization (regex + multi-field AND logic)
- Inline category overrides via dropdown
- Split transactions (mark your share of a shared expense)
- Monthly subscription and per-paycheck deduction tracking
- Single-user, password-protected
Prerequisites
- Node.js 20+
- PostgreSQL 15+
- A Plaid developer account (free for personal use in Sandbox)
Setup
1. Clone and install dependencies
git clone <repo>
cd finance-db
cd server && npm install
cd ../client && npm install
2. Create the database
createdb finance
3. Configure environment variables
Copy .env.example to server/.env and fill in the values:
cp .env.example server/.env
DATABASE_URL=postgresql://user:pass@localhost:5432/finance
ENCRYPTION_KEY= # 64 hex characters (openssl rand -hex 32)
AUTH_PASSWORD_HASH= # bcrypt hash of your password (see below)
SESSION_SECRET= # any long random string (openssl rand -hex 32)
PLAID_CLIENT_ID= # from Plaid dashboard
PLAID_SECRET= # from Plaid dashboard
PLAID_ENV=sandbox # sandbox | production
PORT=3000
Generating AUTH_PASSWORD_HASH:
node -e "const bcrypt = require('bcrypt'); bcrypt.hash('yourpassword', 12).then(console.log)"
Generating ENCRYPTION_KEY:
openssl rand -hex 32
4. Run database migrations
cd server && npm run migrate
5. Start the development servers
# Terminal 1 — backend
cd server && npm run dev
# Terminal 2 — frontend
cd client && npm run dev
The app will be available at http://localhost:5173. The API runs on
http://localhost:3000.
First-Time Use
- Log in with the password you hashed in setup
- Go to Accounts and click Add Account to connect your bank via Plaid
- Toggle off any accounts you don't want to track (investment accounts are excluded automatically)
- Go to Config and set your:
- Paycheck basis date (the date of your first paycheck)
- Per-paycheck deductions (savings, investing, etc.)
- Monthly costs (rent, subscriptions, etc.)
- Budget categories
- Go to Rules and create rules to auto-categorize your transactions
- Click Sync to pull your transactions
- Click New Period to create your first pay period
Project Structure
finance-db/
├── server/ Express + TypeScript API
├── client/ Vue 3 frontend
├── docs/spec.md Full product specification
├── CLAUDE.md Context file for AI coding assistants
└── references/ Original spreadsheet (design reference)
Documentation
See docs/spec.md for the full product specification,
including the data model, all API endpoints, pay period math, and UI
wireframes.