Skip to content

Money Tracker

Personal finance management application for tracking income, expenses, budgets, and financial goals.

Production

Development

  • Dev Server: http://localhost:3000 (run from host)
  • Host Path: /root/projects/money-tracker
  • tmux Session: tmux attach -t money-tracker

Overview

Money Tracker is a personal finance management application that helps track and analyze spending patterns, manage budgets, and achieve financial goals.

Key Features

  • Transaction Tracking: Record income and expenses with categories
  • Budget Management: Set and monitor monthly budgets by category
  • Account Tracking: Multiple accounts (checking, savings, credit cards)
  • Financial Reports: Spending trends, category breakdowns, net worth
  • Receipt Storage: Upload and attach receipts to transactions (via Supabase Storage)
  • Recurring Transactions: Automated tracking of regular bills and income

Tech Stack

  • Framework: Next.js 16 (App Router)
  • UI Library: React 19
  • Styling: Tailwind CSS v4
  • Database: Supabase (PostgreSQL)
  • Authentication: Supabase Auth (shared user pool)
  • Storage: Supabase Storage (for receipt images)
  • Deployment: Kubernetes (k3s)

Database

Schema

Tables are organized in the money_tracker PostgreSQL schema:

-- Example schema structure
money_tracker.accounts
money_tracker.transactions
money_tracker.categories
money_tracker.budgets
money_tracker.recurring_transactions
money_tracker.tags
money_tracker.user_settings

Supabase Connection

Production (Kubernetes - planned): 

NEXT_PUBLIC_SUPABASE_URL: http://10.89.97.214:8000
NEXT_PUBLIC_SUPABASE_ANON_KEY: <shared-anon-key>

Development (LXC): 

NEXT_PUBLIC_SUPABASE_URL: http://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY: <local-dev-key>

See Multi-App Supabase Architecture for details on schema isolation.

Development

Access Project

# Navigate to project (on Proxmox host)
cd /root/projects/money-tracker

Running Dev Server

# Start dev server
npm run dev

# Or attach to existing tmux session
tmux attach -t money-tracker

Local Supabase

# Start Supabase (first time takes 2-3 minutes)
npx supabase start

# Access local Studio
open http://localhost:54323

Database Migrations

# Create new migration
npx supabase migration new migration_name

# Ensure schema is set in migration
echo "SET search_path TO money_tracker;" > supabase/migrations/xxx_migration_name.sql

# Apply migrations locally
npx supabase db reset

# Apply to production (when deployed)
kubectl exec -n supabase postgres-0 -- psql -U postgres < migration.sql

Deployment

Production (Kubernetes)

Money Tracker is deployed to Kubernetes with automated deployment scripts.

Deploy to Production

# Use automated deployment script
/root/tower-fleet/scripts/deploy-money-tracker.sh

# Or manual deployment
kubectl get pods -n money-tracker
kubectl rollout restart deployment/money-tracker -n money-tracker

Architecture

Production (Kubernetes)

Client Request (http://money.internal)
    ↓
DNS Resolution (10.89.97.220)
    ↓
NGINX Ingress Controller (10.89.97.220)
    ↓
money-tracker Service (ClusterIP)
    ↓
money-tracker Pod(s)
    ↓
Supabase API Gateway (Kong: 10.89.97.214:8000)
    ↓
PostgreSQL (money_tracker schema)

Development (Host-Based)

Developer
    ↓
Proxmox Host (localhost:3000)
    ↓
Next.js Dev Server
    ↓
K8s Supabase Sandbox (10.89.97.221:8000)
    ↓
PostgreSQL (money_tracker schema)

Features

Implemented

  • ✅ Transaction recording (income/expense)
  • ✅ Category management
  • ✅ Account tracking (multiple accounts)
  • ✅ Basic reporting and analytics
  • ✅ User authentication (Supabase Auth)

In Progress

  • 🚧 Budget creation and monitoring
  • 🚧 Recurring transactions
  • 🚧 Receipt upload and attachment
  • 🚧 Advanced filtering and search

Planned

  • 📋 Financial goal tracking
  • 📋 Net worth calculation
  • 📋 Investment tracking
  • 📋 Bill reminders and notifications
  • 📋 CSV import/export
  • 📋 Multi-currency support
  • 📋 Mobile app (React Native)

API Endpoints

All API endpoints are available through Supabase PostgREST:

Base URL (Development)

http://localhost:54321/rest/v1/

Base URL (Production - when deployed)

http://10.89.97.214:8000/rest/v1/

Available Endpoints

# Get all transactions for user
GET /rest/v1/transactions?select=*&user_id=eq.{uuid}

# Get accounts
GET /rest/v1/accounts?select=*&user_id=eq.{uuid}

# Get budget summary
GET /rest/v1/budgets?select=*&user_id=eq.{uuid}

# Get spending by category
GET /rest/v1/transactions?select=category,amount&user_id=eq.{uuid}

# Upload receipt
POST /storage/v1/object/money-tracker-receipts/{filename}

All requests require authentication via Authorization: Bearer <token> header.

Configuration

Environment Variables

Required: - NEXT_PUBLIC_SUPABASE_URL - Supabase API URL - NEXT_PUBLIC_SUPABASE_ANON_KEY - Supabase anonymous key - SUPABASE_SERVICE_ROLE_KEY - Supabase service role key (server-side only)

Optional: - NEXT_PUBLIC_DEFAULT_CURRENCY - Default currency (default: USD) - NEXT_PUBLIC_DATE_FORMAT - Date display format (default: MM/DD/YYYY) - NEXT_PUBLIC_ENABLE_INVESTMENTS - Enable investment tracking (default: false)

Storage

Receipt Storage

Receipts are stored in Supabase Storage with the bucket name money-tracker-receipts.

Bucket Configuration: 

INSERT INTO storage.buckets (id, name, public) VALUES
  ('money-tracker-receipts', 'money-tracker-receipts', false);

Upload Pattern: 

const { data, error } = await supabase.storage
  .from('money-tracker-receipts')
  .upload(`${userId}/${transactionId}.pdf`, file)

Access Pattern: 

const { data } = await supabase.storage
  .from('money-tracker-receipts')
  .createSignedUrl(`${userId}/${transactionId}.pdf`, 3600)

Troubleshooting

Common Issues

Cannot connect to Supabase: 

# Check local Supabase is running
npx supabase status

# Restart if needed
npx supabase stop
npx supabase start

Transactions not saving: 

# Check database schema
npx supabase db reset

# Verify tables exist
psql -h localhost -p 54322 -U postgres -c "\dt money_tracker.*"

Dev server won't start: 

# Check if port 3000 is in use
lsof -i :3000

# Check tmux session
tmux ls
tmux attach -t money-tracker

Receipt upload failing: 

# Verify bucket exists
# In Supabase Studio: Storage > Buckets

# Check RLS policies
# Storage > money-tracker-receipts > Policies

Data Model

Core Entities

Accounts - Checking, savings, credit cards, cash - Track current balance - Link to transactions

Transactions - Income or expense - Amount, date, description - Category, account, tags - Optional receipt attachment

Categories - Hierarchical (parent/child) - Budget assignments - Spending analytics

Budgets - Monthly budget by category - Track spending vs budget - Rollover settings

Recurring Transactions - Bills, subscriptions, paychecks - Frequency (monthly, weekly, etc.) - Auto-create transactions

Roadmap

Phase 1: Core Features (Current)

  • ✅ Basic transaction tracking
  • ✅ Account management
  • ✅ Category system
  • 🚧 Budget monitoring

Phase 2: Enhanced Features

  • 📋 Receipt management
  • 📋 Recurring transactions
  • 📋 Advanced reporting
  • 📋 Data import/export

Phase 3: Advanced Features

  • 📋 Investment tracking
  • 📋 Goal tracking
  • 📋 Multi-currency
  • 📋 Mobile app

Phase 4: Production Deployment

  • 📋 Kubernetes manifests
  • 📋 Production database migration
  • 📋 CI/CD pipeline
  • 📋 Monitoring and alerts

Support