PocketFinance

Imported from EvanManHS/PocketFinance (AGENTS.md). Install upstream with npx skills add EvanManHS/PocketFinance. Copyright stays with the author.

PocketFinance — Feature Reference

Privacy-aware personal financial planner with on-device AI. Final Year Project, .

Architecture

PocketFinance/
├── backend/           Python 3.13+ / FastAPI / SQLAlchemy / SQLCipher
│   ├── app/
│   │   ├── main.py              Entry point, startup, CORS (allow all for LAN)
│   │   ├── config.py            Centralized config, persisted settings
│   │   ├── api/routes/          REST endpoints
│   │   │   ├── transactions.py  CRUD, stats, suggest-category
│   │   │   ├── categories.py    CRUD for spending categories
│   │   │   ├── budgets.py       Budget CRUD, status, summary, renewal
│   │   │   ├── upload.py        Receipt image + PDF statement upload
│   │   │   ├── coaching.py      Financial coach (streaming), budget recommendations
│   │   │   ├── knowledge.py     Knowledge base file CRUD, indexing
│   │   │   ├── export.py        CSV/ZIP export, CSV import
│   │   │   ├── settings.py      Provider config, built-in model management, QR code, network info
│   │   │   ├── userdata.py      Key-value store for frontend state (goals, planner, coach history)
│   │   │   └── health.py        Health check
│   │   ├── models/
│   │   │   ├── vision_llm.py    Vision model for receipt/statement parsing
│   │   │   ├── categorization.py Text LLM for categorization + coaching + streaming
│   │   │   ├── knowledge_base.py Chroma vector DB, RAG search, content loading
│   │   │   └── builtin_llm.py   GGUF model loading via llama-cpp-python
│   │   ├── parsers/
│   │   │   ├── receipt_parser.py  Receipt image → structured data
│   │   │   └── statement_parser.py PDF bank statement → transactions
│   │   ├── database/
│   │   │   ├── models.py        Transaction, Category, Budget, MerchantCategory, UserPreference
│   │   │   ├── connection.py    SQLCipher encrypted DB manager
│   │   │   └── encryption.py    AES-256 + Argon2id key derivation
│   │   └── services/
│   │       ├── transaction_service.py
│   │       ├── categorization_service.py  Hybrid: rule-based + LLM + cached
│   │       ├── budget_service.py
│   │       └── coaching_service.py        RAG pipeline, streaming, conversation persistence
│   ├── tests/                   pytest unit tests (86+)
│   ├── data/                    Local storage (gitignored)
│   │   ├── knowledge_base/content/  15 financial education markdown files
│   │   ├── models/              GGUF model files for built-in provider
│   │   ├── settings.json        Persisted provider/model config
│   │   └── financial_planner.db Encrypted SQLite database
│   └── pyproject.toml           Core deps + optional [ai] extras
│
├── frontend/          React 18 / TypeScript / Vite
│   ├── src/
│   │   ├── pages/
│   │   │   ├── Landing.tsx      Homepage with feature showcase
│   │   │   ├── Dashboard.tsx    Transaction list, charts, budget summary, export/import
│   │   │   ├── Upload.tsx       Receipt + statement upload with tab navigation
│   │   │   ├── Budget.tsx       Budget management, goal tracking, template table
│   │   │   ├── BudgetRecommendation.tsx  AI Planner: goal planner + budget allocation
│   │   │   ├── Coach.tsx        Financial coach chatbot with streaming + citations
│   │   │   ├── KnowledgeBase.tsx Knowledge base file management + indexing
│   │   │   ├── Settings.tsx     Provider config, built-in models, mobile QR code
│   │   │   └── NotFound.tsx     404 page
│   │   ├── components/
│   │   │   ├── Layout.tsx       Sidebar navigation, responsive
│   │   │   ├── Charts.tsx       Pie chart + line chart (Recharts)
│   │   │   └── Skeleton.tsx     Loading skeletons
│   │   ├── services/api.ts      Type-safe API client (dynamic base URL for LAN)
│   │   └── types/api.ts         TypeScript interfaces
│   ├── public/
│   │   ├── manifest.json        PWA manifest
│   │   ├── sw.js                Service worker (cache-first for static, network-first for API)
│   │   └── icons/               PWA icons (SVG + PNG)
│   └── e2e/                     Playwright E2E tests (24)
│
├── scripts/
│   ├── start.sh                 Production: backend + static frontend serving
│   ├── start-app.sh             Dev: backend + Vite dev server
│   ├── start-backend.sh         Dev: backend only
│   └── start-frontend.sh        Dev: frontend only
│
└── .github/workflows/release.yml  CI: tests + build + GitHub Release zip

Features

1. Receipt & Statement Parsing

• Drag-and-drop upload for receipt images (JPEG, PNG) and PDF bank statements
• Vision LLM extracts merchant, amount, date, items from images
• PDF parser (pdfplumber) handles multi-page bank statements
• Auto-categorization with confidence scoring after parsing
• Tab navigation between receipt and statement upload modes
• Processing status indicators and parsed data preview

2. Transaction Management

• Full CRUD for transactions with merchant, amount, date, category, description
• Review workflow: AI-parsed transactions flagged for review, quick-mark or edit to approve
• Category display with color-coded badges
• AI Suggest button in edit modal for smart category suggestions
• Spending analytics: by-category breakdown, daily trends, summary stats
• CSV import with duplicate detection and validation

3. Smart Categorization

• Hybrid 3-tier system:
  • Rule-based: 60+ keyword patterns, instant, 85% confidence
  • LLM-based: Qwen3/built-in model, 2-3s, 75% confidence
  • Cached: merchant-category dictionary from user corrections, 90% confidence
• Merchant-category learning from user feedback
• Confidence scoring with review flags below 70%

4. Budget System

• Create budgets per category or custom budgets
• Budget template table with all categories, inline amount editing
• Progress bars with color-coded status (good/warning/exceeded)
• Toggle active/inactive without deletion
• Duplicate prevention (one active budget per category)
• Budget summary statistics on dashboard
• Budget renewal for next period
• Goal tracking with manual create/edit/dismiss

5. AI Planner (Goal Planner + Budget Recommendation)

• Two tabs: Goal Planner and Budget Recommendation
• Goal Planner: monthly income, savings plan, goals, timeframe (short/mid/long), target amount
  • Streaming LLM response with spending analysis
  • Persisted to database (syncs across devices)
• Budget Recommendation: monthly income + strategy (relaxed/balanced/aggressive)
  • Structured BUDGET: lines parsed into table (Savings / Essential / Optional sections)
  • Normalized amounts to match income
  • "Apply All to Budget" creates/updates budgets from recommendations
  • Persisted to database

6. Financial Coach

• RAG-based chatbot with 15 financial education documents
• Streaming responses with real-time token display
• Knowledge base citation: sources shown as clickable chips with content preview
• Conversation history persisted to database (survives reload/restart, syncs across devices)
• Context-aware: references user's budgets, goals, income, spending patterns, savings plan
• Thinking process separation (collapsible <think> tag handling)
• Regenerate response button
• Clear chat functionality

7. Knowledge Base Management

• Dedicated page listing all content files grouped by category
• Indexed/not-indexed status badges per file
• CRUD: create new markdown files, edit existing, delete
• Per-file indexing and full re-index (drops + recreates Chroma collection)
• Handles embedding dimension mismatches automatically
• 15 built-in financial education documents across 5 categories

8. Dashboard

• Transaction list with filtering
• Spending pie chart (by category) and line chart (daily trend, 30 days)
• Budget summary cards (active budgets, good/warning/exceeded counts)
• Stats cards: total spending, transaction count, needs review count
• Export: CSV download, password-protected ZIP
• Import: CSV upload with validation and results summary

9. Settings & Provider Management

• Multi-provider support: Built-in (GGUF), LM Studio, Ollama, OpenAI, Groq, Custom
• Built-in provider: load/unload chat + embedding GGUF models from backend/data/models/
• External provider: test connection, list available models, select from dropdown
• All settings persisted to backend/data/settings.json
• Auto-load built-in models on startup if configured
• Mobile Access section: QR code for LAN access, local IP display

10. Mobile & PWA

• Progressive Web App: manifest.json, service worker, installable on mobile
• Dynamic API base URL (window.location.hostname) for LAN access
• Vite dev server binds to 0.0.0.0 for LAN
• CORS allows all origins (safe for local-only app)
• QR code generation endpoint for easy phone connection
• "Add to Home Screen" for app-like experience

11. Data Export & Import

• CSV export of all transactions
• Password-protected ZIP export (CSV + README)
• CSV import with validation, duplicate detection, detailed results
• All data stays local — no cloud

12. Security & Privacy

• SQLCipher AES-256 encrypted database with Argon2id key derivation
• All AI processing local (no external API calls by default)
• No telemetry, no analytics, no cloud uploads
• Password-protected ZIP exports
• CORS open for LAN but no internet exposure

13. Testing

• Backend: 86+ pytest unit tests (mocked AI, in-memory SQLite)
• Frontend: 24 Playwright E2E tests (navigation, dashboard, upload, complete flows)
• CI: GitHub Actions runs tests + builds frontend on tag push
• Lightweight CI deps (AI/ML packages excluded via optional extras)

14. Deployment

• GitHub Actions release workflow: tag push → test → build → zip → GitHub Release
• Release zip contains: backend/, frontend-dist/, scripts/start.sh, README.md
• scripts/start.sh for production (serves static files + backend)
• scripts/start-app.sh for development (Vite hot reload + backend)

Tech Stack

Key Design Decisions

• Privacy-first: all processing local, encrypted storage, no cloud
• Hybrid categorization: instant rule-based + slower LLM fallback
• Optional AI deps: core app works without torch/chromadb (for CI and lightweight installs)
• Dynamic API URL: window.location.hostname enables LAN access without config
• Conversation + planner state persisted to DB via UserPreference key-value store
• Knowledge base dimension mismatch auto-detected and collection rebuilt
• Similarity score formula: 1 - distance/2 for Chroma cosine distance (range 0-2)

API Endpoints Summary

Pages (Frontend Routes)