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%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-08-02 19:28:22 -04:00
client Dropped root package.json in order to allow for docker builds. I didn't want to recreate a lockfile and that would have been necessary with the workspace set up. (I also verified it still works) 2026-08-02 19:28:07 -04:00
docs Added logging and fixed issues with initial standing-up of tool 2026-08-01 11:01:44 -04:00
references Initial commit of agentic code base 2026-05-25 12:56:57 -04:00
scripts Added local build tools, added a health check for the db 2026-08-01 16:18:30 -04:00
server Dropped root package.json in order to allow for docker builds. I didn't want to recreate a lockfile and that would have been necessary with the workspace set up. (I also verified it still works) 2026-08-02 19:28:07 -04:00
.env.example Dropped node modules from repo. That was a big mistake. Updated .gitignore. 2026-05-31 15:14:38 -04:00
.gitignore Dropped node modules from repo. That was a big mistake. Updated .gitignore. 2026-05-31 15:14:38 -04:00
CLAUDE.md Initial commit of agentic code base 2026-05-25 12:56:57 -04:00
deploy.md Added logging and fixed issues with initial standing-up of tool 2026-08-01 11:01:44 -04:00
docker-compose.local.yml Dropped node modules from repo. That was a big mistake. Updated .gitignore. 2026-05-31 15:14:38 -04:00
docker-compose.yml Added logging and fixed issues with initial standing-up of tool 2026-08-01 11:01:44 -04:00
Makefile Broke docker command out 2026-08-02 19:28:22 -04:00
README.md Initial commit of agentic code base 2026-05-25 12:56:57 -04:00

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


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

  1. Log in with the password you hashed in setup
  2. Go to Accounts and click Add Account to connect your bank via Plaid
  3. Toggle off any accounts you don't want to track (investment accounts are excluded automatically)
  4. 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
  5. Go to Rules and create rules to auto-categorize your transactions
  6. Click Sync to pull your transactions
  7. 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.