Personal Finances

A privacy-first personal finance management system with AI-powered insights. Built to be better than Copilot (the financial app) with bulletproof data quality.

Core Philosophy

1. Data Quality First: Bad data = bad advice. Robust import, validation, and categorization.
2. Privacy First: All data stays local. You control what gets analyzed.
3. LLM Agnostic: Plugin architecture for different AI providers.
4. No Bullshit: No mocks, no fake data, no misleading information.

Features

✅ Transaction Management

• CSV Import with intelligent parsing
• Duplicate Detection prevents importing the same transactions
• Merchant Normalization cleans up transaction descriptions
• Automatic Categorization with learning system
• Data Quality Tracking flags anomalies and issues

✅ Subscription Detection

• Automatic Detection finds recurring payments
• Hidden Subscriptions identifies small recurring charges you might miss
• Cost Analysis shows monthly/yearly totals

✅ Financial Snapshot

• Comprehensive Reports for LLM analysis
• Net Worth Tracking
• Cash Flow Analysis over different periods
• Investment Portfolio tracking
• Category Breakdown with spending trends

✅ Learning System

• Smart Categorization Rules that improve over time
• Manual Corrections train the system
• Confidence Scoring flags transactions needing review

Architecture

personal-finances/
├── packages/
│   ├── database/          # Prisma schema, migrations
│   ├── core/              # Business logic, services
│   ├── api/               # REST API (Fastify)
│   └── cli/               # Command-line interface
├── .env                   # Local configuration
└── data/                  # SQLite database (created on first run)

Getting Started

Prerequisites

• Node.js >= 20
• pnpm >= 8

Installation

# Install dependencies
pnpm install

# Setup database
pnpm db:generate
pnpm db:migrate

# Seed default categories
cd packages/database && tsx prisma/seed.ts

# Copy environment file
cp .env.example .env

Usage

CLI Commands

# Create an account
pnpm --filter @personal-finances/cli dev accounts add

# Import transactions from CSV
pnpm --filter @personal-finances/cli dev import <file.csv>

# Review uncategorized transactions
pnpm --filter @personal-finances/cli dev review

# Detect subscriptions
pnpm --filter @personal-finances/cli dev subscriptions detect

# Find hidden subscriptions
pnpm --filter @personal-finances/cli dev subscriptions hidden

# Generate financial snapshot
pnpm --filter @personal-finances/cli dev snapshot

# Export snapshot for Cursor/LLM analysis
pnpm --filter @personal-finances/cli dev snapshot -o financial-report.md

API Server

# Start API server
pnpm --filter @personal-finances/api dev

# API will be available at http://localhost:3000

API Endpoints

Accounts

• GET /api/accounts - List all accounts
• POST /api/accounts - Create account
• PATCH /api/accounts/:id - Update account

Transactions

• GET /api/transactions - List transactions (with filters)
• GET /api/transactions/review - Get transactions needing review
• PATCH /api/transactions/:id/categorize - Manually categorize

Import

• POST /api/imports/csv - Import CSV file
• GET /api/imports/history - Get import history

Subscriptions

• GET /api/subscriptions - List active subscriptions
• POST /api/subscriptions/detect - Detect subscriptions
• GET /api/subscriptions/hidden - Find hidden subscriptions

Snapshot

• GET /api/snapshot - Generate financial snapshot (JSON)
• GET /api/snapshot/text - Snapshot as formatted text
• GET /api/snapshot/markdown - Snapshot as markdown file

Categories

• GET /api/categories - List categories
• POST /api/categories - Create category
• GET /api/categories/:id/rules - Get categorization rules

CSV Import Format

The system intelligently detects common CSV formats. Minimum required columns:

• Date (various formats supported)
• Description
• Amount

Optional columns:

• Type (debit/credit)
• Merchant
• Category

Example CSV

Date,Description,Amount
2024-01-15,Whole Foods Market,125.50
2024-01-16,Netflix,15.99
2024-01-17,Shell Gas Station,45.00

Using with Cursor/AI

1. Generate a financial snapshot:

   pnpm --filter @personal-finances/cli dev snapshot -o report.md

2. Open report.md in Cursor

3. Ask questions:

   • "Show me all my subscriptions and recommend which to cancel"
   • "I'm in financial trouble, create a recovery plan"
   • "Analyze my spending and find where I'm wasting money"
   • "Review my investment portfolio and suggest rebalancing"

Data Quality

The system tracks data quality with:

• Duplicate detection (hash-based + fuzzy matching)
• Validation errors (invalid dates, amounts, etc.)
• Confidence scoring (0-1 for categorizations)
• Anomaly detection (unusual amounts, future dates, etc.)
• Review queue for low-confidence transactions

Privacy & Security

• Local-first: All data stored in local SQLite database
• No telemetry: Zero tracking or analytics
• You control exports: Explicitly generate reports for AI analysis
• Future: Encryption at rest option

Development

# Run in development mode
pnpm dev

# Build all packages
pnpm build

# Clean build artifacts
pnpm clean

# Database commands
pnpm db:migrate    # Run migrations
pnpm db:studio     # Open Prisma Studio
pnpm db:generate   # Generate Prisma Client

Future Roadmap

• LLM provider plugins (OpenAI, Anthropic, Ollama)
• Web UI
• Bank API integrations (Plaid)
• Budget tracking and forecasting
• Bill payment reminders
• Multi-currency support
• Data encryption at rest
• Self-hosted cloud sync (optional)
• Mobile app
• Tax optimization insights

Contributing

This is a personal project being built from scratch. The focus is on quality, privacy, and actually useful AI insights.

License

Private use only (for now).

---

Built with TypeScript, Prisma, Fastify, and a commitment to data quality over everything else.