Skip to content

Latest commit

 

History

History
235 lines (172 loc) · 6.17 KB

README.md

File metadata and controls

235 lines (172 loc) · 6.17 KB

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.