A self-hosted personal finance web application. Track income, expenses, investments, budgets, and savings goals. AI-powered financial assistant and receipt OCR built in.

Live at: https://pfm.ngodanguyen.tech

Features Overview
Getting Started
Dashboard
Transactions
Accounts
Categories
Budgets
Goals & Savings
Investments
AI Assistant
Reports & Export
Settings
Recurring Transactions
CSV Import
Receipt OCR
USD → VND Rate Widget
Keyboard Shortcuts & Tips

Features Overview

Module	What it does
Dashboard	Net worth, cash flow chart, budget gauges, AI insight, USD/VND rate
Transactions	Income + expense entry, transfer, filter, search, receipt upload
Accounts	Multiple bank/cash/credit accounts, auto-calculated balances
Categories	Custom expense + income categories with color and icon
Budgets	Monthly spending limits per category with progress tracking
Goals	Savings goals with contribution tracking and projected completion
Investments	Stock/ETF/crypto/real estate portfolio with live price fetch
AI Assistant	Chat with your finances via Groq (free), daily auto-insight
Receipt OCR	Drag-drop a receipt image — AI extracts and fills the form
Reports	Monthly/quarterly/yearly summaries, net worth history, PDF/CSV/Excel export
Settings	Profile, currency, recurring rules, CSV import, password

Getting Started

Navigate to https://pfm.ngodanguyen.tech
Enter the username and password created during setup (python scripts/init_db.py)
Check "Remember me" to stay logged in across browser sessions

Recommended Setup Order

Add accounts — add your bank accounts, cash wallet, and credit cards first (Settings sidebar → Accounts)
Review categories — default categories are already seeded; add custom ones if needed
Set your currency — go to Settings → Profile and set your app currency (USD, VND, etc.)
Add transactions — start entering income and expenses
Set budgets — once you have categories, set monthly limits
Create goals — add savings goals and start contributing
Add investments — track your portfolio holdings
Set recurring rules — automate repeating income/expenses

Dashboard

The dashboard is the home screen — accessible from the sidebar or by clicking the PFM logo.

Period Selector

Three buttons in the top-right of the topbar:

This Month — income/expenses for the current calendar month
Last Month — previous calendar month
Custom — opens a date picker modal; choose any start and end date

The period affects the summary cards and recent transactions feed. Charts always show fixed windows (6 months for cash flow, etc.).

Summary Cards

Four cards across the top:

Income — total income for the selected period (green)
Expenses — total expenses for the selected period (red)
Net Cash Flow — income minus expenses; green if positive, red if negative
Net Worth — total assets minus liabilities across all accounts

Cash Flow Chart

Bar chart showing the last 6 months of income (green bars) vs expenses (red bars). Hover over bars to see exact amounts.

Top Spending

Right of the cash flow chart — shows your top 5 expense categories for the period with horizontal progress bars. Widest bar = highest spending.

Dark card below the top spending section. Shows today's USD to VND exchange rate for reference. Click the widget to reveal a 30-day trend chart. Click the ↻ button to force-refresh the rate without reloading the page. See USD → VND Rate Widget for details.

AI Daily Insight

Dark card above the accounts section. Shows a 3–5 sentence AI-generated summary of your finances for the day. Generated automatically at midnight. Click "Open AI →" to go to the full chat interface.

Accounts Panel

Left of the recent transactions — lists all active accounts with their current balance. Green = positive, red = negative (credit card debt). Click "+" to add a new account.

Recent Transactions

Last 8 income and expense transactions. Click "View all" to go to the full transaction list.

Quick Add Buttons

Two buttons in the page header:

+Income (green) — opens new income form
+Expense (red) — opens new expense form

Transactions

Viewing Transactions

Navigate via Transactions in the sidebar. Two tabs at the top:

Expenses — shows expense transactions with a count badge
Income — shows income transactions with a count badge

Transactions are ordered newest first, paginated at 30 per page.

Filtering

A filter bar appears below the tabs:

Search — matches against the description field (case-insensitive)
Category — filter by a single category
Account — filter by a single account
From / To — date range filter
Click the magnifying glass button to apply filters
Click the ✕ button to clear all filters and reset to defaults

Adding a Transaction

From the sidebar: click "Add Income" or "Add Expense" From the dashboard: use the +Income / +Expense buttons From the transaction list: use the topbar buttons

New Expense / Income Form Fields

Field	Required	Notes
Description	Yes	What the transaction was for
Amount	Yes	Positive number only
Date	Yes	Defaults to today
Account	Yes	Which account to debit/credit
Category	No	Helps with budgets and reports
Notes	No	Free text, up to 500 characters

AI Receipt Scanner (on new expense form)

A purple panel sits above the form. Drop a receipt image onto it (or click to browse). The AI extracts the amount, date, merchant name, and category and fills the form fields automatically. Review the filled values before saving — highlighted fields (green flash) show what was auto-filled. See Receipt OCR for details.

Editing a Transaction

Click Edit on any transaction row. Same form as adding, with an additional receipt section:

If a receipt is attached: shows filename with a Re-extract button (re-runs OCR on the stored file) and a Remove button
If no receipt: shows an upload field; selecting an image file auto-triggers OCR

Deleting a Transaction

Click Del on any transaction row. A confirmation prompt appears. Deletion is permanent and account balances are recalculated immediately.

Transfers Between Accounts

Click Transfer in the topbar. Select source account, destination account, amount, and date. This creates a single transfer transaction that debits the source and credits the destination. Transfers do not appear on the Income or Expense tabs — they are excluded from income/expense totals.

Accounts

Adding an Account

Settings sidebar → Accounts → New Account (or from dashboard Accounts panel → "+").

Field	Notes
Account Name	e.g. "Chase Checking", "Cash Wallet", "Visa Card"
Type	checking / savings / cash / credit_card / crypto / investment / other
Color	Click a color swatch — used for visual identification
Icon	Click an icon swatch — appears throughout the app
Notes	Optional description

Account Balances

Balances are automatically calculated from all transactions linked to that account — you do not enter a balance manually. When you add a transaction, the account balance updates instantly.

Formula:

Balance = sum(income) - sum(expenses) - sum(transfers_out) + sum(transfers_in)

For a brand-new account with no transactions, balance is 0. To set a starting balance, add an income transaction dated your desired start date with the description "Opening balance."

Removing an Account

Click the three-dot menu (⋯) on an account card → Remove. This is a soft delete — the account is hidden but its transactions remain in the database and still affect totals. You cannot permanently delete an account with transactions.

Budgets

Navigate via Budgets in the sidebar.

Use the ◀ and ▶ arrows to move between months. The current month is the default.

Setting a Budget

Click Add Budget in the topbar (or "Set Budget" next to an unbudgeted category).

Field	Notes
Category	Expense categories only
Monthly Limit	Maximum spend for this category this month
Roll over unused amount	If checked, unspent budget carries forward to next month

Budget Progress Bars

Each category row shows:

Category name and icon
Amount spent (colored by status)
Budget limit
Progress bar: green (< 80%) → amber (80–99%) → red (100%+)
Remaining amount (or over-budget amount in red)

Unbudgeted Spending

Categories with spending but no budget appear at the bottom of the table with a yellow "no budget" badge and a "Set Budget" button.

Copy from Previous Month

Click Copy from YYYY-MM button (top right or empty state) to duplicate all budget entries from the previous month. Existing budgets for the current month are not overwritten — only missing ones are created.

Editing / Deleting a Budget

Click Edit or Del on any budget row. Deleting a budget does not delete the transactions — it only removes the limit.

Goals & Savings

Navigate via Goals in the sidebar.

Emergency Fund Tracker

A yellow card at the top (appears once you have 3+ months of expense data). Shows:

Average monthly expense (last 3 months)
Liquid assets (checking + savings + cash accounts combined)
3-month target and 6-month target with progress bars
Months covered: how long your liquid assets would last at current spending

Creating a Goal

Click New Goal in the topbar.

Field	Notes
Goal Name	e.g. "Vacation Fund", "Emergency Fund", "New Laptop"
Target Amount	How much you want to save
Target Date	Optional deadline
Linked Account	Optional — associates the goal with a specific account
Description	Optional notes
Color	Visual identifier (circle swatches)
Icon	Visual identifier (icon swatches)

Goal Cards

Each active goal shows:

Progress bar (fills with goal color)
Current amount saved / target amount
Completion percentage
Projected completion date (calculated from average monthly contribution history — only shown after 2+ contributions)
Description (if set)
Add Contribution button (styled in goal color)

Adding a Contribution

Click Add Contribution on a goal card or from the three-dot menu. Enter amount, date, and optional notes. When the total reaches the target, the goal auto-completes and moves to the "Completed Goals" section.

Contribution History

Three-dot menu → History — shows all contributions with dates and amounts, plus the projected completion date. Individual contributions can be deleted (recalculates goal total and un-completes if needed).

Completed Goals

Shown at the bottom of the page in a compact table. Last 5 completed goals displayed.

Investments

Navigate via Investments in the sidebar.

Portfolio Overview

Summary cards at the top:

Total Value — current market value of all holdings
Total Cost — total amount invested (cost basis)
Unrealized P&L — gain or loss vs cost basis
Return — percentage return

Allocation chart — doughnut chart showing portfolio split by asset type (stock, ETF, crypto, real estate, bond, cash, other). Each slice is color-coded. Click a row in the legend for exact values.

Holdings table — all active holdings. Click any row to go to the detail page.

Adding a Holding

Click Add Holding in the topbar.

Field	Notes
Asset Name	Full name, e.g. "Apple Inc.", "Bitcoin"
Asset Type	stock / ETF / crypto / real_estate / bond / cash / other
Ticker Symbol	Yahoo Finance format: AAPL, BTC-USD, ETH-USD, VNM. Click Check to verify

After saving, you are taken to the detail page to record your first buy transaction.

Ticker Format (Yahoo Finance)

US Stocks: AAPL, MSFT, GOOGL
ETFs: VOO, QQQ, VTI
Crypto: BTC-USD, ETH-USD, BNB-USD
Vietnamese stocks: VNM (VanEck Vietnam ETF on NYSE)
Other markets: use Yahoo Finance suffix, e.g. VIC.VN for Vingroup on HOSE

Holding Detail Page

Shows the holding summary (shares, avg cost, current price, market value, P&L) and transaction history. Current price timestamp is shown below the price.

Recording a Transaction

On the detail page, click Add Transaction in the topbar.

Transaction Type	What it does
Buy	Adds shares, increases cost basis
Sell	Reduces shares, adjusts cost basis (FIFO)
Dividend	Records a dividend payment (does not change shares)
Split	Adds shares without changing cost (stock split)

The ↓ button next to the price field fetches the current live price from Yahoo Finance and fills it in. The "Estimated Total" preview updates as you type shares and price.

After saving, shares and average cost basis are automatically recalculated from the full transaction history.

Refreshing Prices

Click Refresh Prices in the topbar on the portfolio page to fetch current prices for all holdings with ticker symbols. Prices are also automatically updated daily at 4PM (weekdays) via a background job.

Removing a Holding

On the detail page, click Remove (top right of the holding card). This is a soft delete — the holding is hidden but transaction history is preserved.

AI Assistant

Navigate via AI Assistant in the sidebar.

Chat Interface

Type a question in the text box at the bottom and press Enter (or click the send button). The response streams word-by-word in real time.

Shift+Enter adds a new line without sending.

The AI has access to:

Last 90 days of transactions (description, category, amount, date)
Current month income/expense totals and budget status
Active savings goals with progress
Investment portfolio summary
Net worth

No personal names, account names, or identifying details are sent to Groq — only aggregated financial figures.

Daily Insight

A dark card on the right shows today's auto-generated insight (3–5 sentences covering spending, budget alerts, and a tip). Generated automatically at midnight. If not yet generated for today, click Generate Now. Click Regenerate to get a fresh one.

Chat History

Click History in the topbar. Shows all past chat responses and daily summaries with timestamps and token counts. Paginated at 20 per page.

AI Model

The model can be changed in Settings → Profile → AI Model:

llama-3.3-70b-versatile — best quality, slightly slower
llama-3.1-8b-instant — faster, slightly less detailed

Error States

"AI assistant is not configured" — GROQ_API_KEY is missing from .env
"Rate limit reached" — too many requests; wait a moment and retry
"Invalid Groq API key" — check the key at console.groq.com

Reports & Export

Navigate via Reports in the sidebar.

Report Types

Four tabs at the top:

Monthly — income, expenses, net, savings rate for a single month. Bar chart + expense doughnut.

Quarterly — same metrics for a quarter (Q1–Q4), plus monthly breakdown bars within the quarter.

Yearly — full year summary with monthly breakdown, average monthly income/expense.

Tax Year — income by source and expenses by category for a full calendar year, plus a full list of all income transactions for the year. Useful for tax preparation.

Selecting a Period

Use the year/month/quarter dropdowns next to the period tabs and click Go.

Charts

Period chart — bar chart of income vs expenses for the selected period (or monthly breakdown for quarterly/yearly).

Expense breakdown — doughnut chart of expenses by category. Hover for exact amounts. Top 5 categories listed below with amounts.

Net worth history — line chart of net worth over time (requires monthly snapshots to be saved). Dashed line shows total assets. Click Snapshot Now to save today's values.

Category spending trends — line chart of top 6 expense categories over the last 6 months. Useful for spotting trends.

Exporting

Three export buttons in the topbar:

Button	Format	Contents
CSV	`.csv`	All transactions for the selected period, plain text
Excel	`.xlsx`	Color-coded rows (green=income, red=expense), formatted amounts, totals row
PDF	`.pdf`	Clean printable report with summary cards and expense breakdown table

Exports use the period selected in the current report view (year + month/quarter).

Settings

Navigate via the gear icon at the bottom of the sidebar, or Settings → Profile.

Profile

Setting	Notes
Display Name	Shown in the topbar
Email	For reference only (no email features yet)
Timezone	Used for scheduled jobs
Currency	App-wide currency code (USD, VND, EUR, etc.)
Currency Symbol	Auto-set when currency is changed
AI Model	Groq model for chat and daily insights

Click Save Profile to apply. Currency and symbol changes take effect immediately throughout the app.

Changing Password

Settings → Password. Requires current password + new password (min 6 characters) + confirmation.

Recurring Transactions

Navigate via Settings → Recurring (also accessible from Settings landing page).

What It Does

Recurring rules automatically create transactions on a schedule. At 6AM daily, the system checks all active rules and creates any transactions that are due (including any missed occurrences if the server was down).

Creating a Rule

Click New Rule.

Field	Notes
Name	Label for the rule, e.g. "Monthly Rent"
Type	income or expense
Description	Used as the transaction description
Amount	Fixed amount each occurrence
Frequency	daily / weekly / biweekly / monthly / quarterly / yearly
Account	Which account to debit/credit
Category	Optional
Start Date	First occurrence date
End Date	Optional — leave blank for no end date

Managing Rules

The rules table shows all rules with their next run date, frequency, and status. Available actions:

Edit — change any field (does not affect already-created transactions)
Pause / Enable — temporarily disable without deleting
× — delete the rule (already-created transactions are preserved)

Run Now

Click Run Now in the topbar to immediately process all due rules. Useful after creating a new rule that has a past start date, or after the server was offline.

Upcoming Preview

Right panel shows all upcoming recurring transactions for the next 30 days in date order, with amounts and type badges.

CSV Import

Navigate via Settings → Import.

CSV Format

date,type,description,category,account,amount,notes
2025-01-15,expense,Groceries,Food & Dining,Checking,85.50,Weekly shop
2025-01-16,income,Salary,Salary,Checking,3000.00,

Required columns: date, type, description, amount

Optional columns: category, account, notes

Accepted date formats: YYYY-MM-DD, MM/DD/YYYY, DD/MM/YYYY

Type values: must be exactly income or expense (lowercase)

Import Process

Choose your CSV file
Select a Default Account — used when the account column is missing or the name doesn't match any of your accounts
Check Skip duplicate transactions (recommended) — skips rows where date + description + amount + type exactly match an existing transaction
Click Preview Import
Review the preview table:
- ⚠ yellow warning on category = category name not found (will be uncategorised)
- ⚠ yellow warning on account = account not found (will use default account or be unlinked)
Click Confirm Import to save all rows

Account and category matching is case-insensitive. If your CSV has food & dining it will match the Food & Dining system category.

Receipt OCR

Receipt OCR uses the Groq llama-4-scout vision model to extract transaction data from a photo of a receipt.

On New Expense Form

A purple panel with a dashed border appears above the transaction form:

Drag and drop a receipt image onto the panel, OR click the panel to browse for a file
Accepted formats: JPG, PNG, GIF, WEBP (max 10MB — PDF not supported for OCR)
The panel shows a spinning animation while scanning
On success: the panel turns green and form fields flash green to show what was filled:
- Description ← merchant name (e.g. "McDonald's")
- Amount ← total from receipt
- Date ← date on receipt (falls back to today if not found)
- Category ← AI's best guess matched to your system categories
- Notes ← brief description
Review all fields before clicking Save — OCR is not perfect, especially on low-quality photos
You can drop another receipt to re-scan and overwrite the filled values

On Edit Transaction Form

If a receipt is already attached:

A purple Re-extract button appears next to the receipt filename
Click it to re-run OCR on the stored file and update the form fields

If no receipt is attached:

An upload field appears
Selecting a JPG/PNG/WEBP file automatically triggers OCR and opens the scanner panel

Tips for Best OCR Results

Use a well-lit, in-focus photo
Make sure the total amount is clearly visible
Flatten crumpled receipts before photographing
Portrait orientation works better than landscape
Higher resolution = better accuracy
If OCR misreads the amount, correct it manually — amounts are the most important field

What OCR Cannot Do

Read multi-page receipts (only the uploaded image is processed)
Handle PDF receipts (PDF format is excluded from OCR; it can still be uploaded as an attachment)
Guarantee 100% accuracy — always review extracted values before saving

The dark widget on the dashboard shows the current USD to VND exchange rate. This is for reference only — it does not affect any transactions or calculations in the app.

How the Rate is Fetched

Primary: Yahoo Finance forex (USDVND=X via yfinance) — most reliable
Fallback: ExchangeRate API (open.er-api.com) — free, no key required
Stale fallback: Last known rate from database — shown with a ⚠ indicator

The rate is cached once per day. The daily cron job at 8AM always force-fetches a fresh rate.

Refreshing Manually

Click the ↻ button (top-right of the widget) to force-fetch a fresh rate without reloading the page. The rate, date, and source label update in-place.

30-Day History Chart

Click anywhere on the widget (except the ↻ button) to toggle a compact line chart showing the rate trend over the last 30 days.

Stale Indicator

If the cached rate is from a previous day and all live sources fail, a ⚠ symbol appears next to the date. This typically means the server has no internet access or the APIs are temporarily unavailable.

Keyboard Shortcuts & Tips

The sidebar collapses on desktop — click the ☰ button in the topbar to toggle. State is remembered across page loads.
On mobile, the sidebar slides in as an overlay — tap anywhere outside to close it.

Forms

On the AI chat input: Enter sends the message, Shift+Enter adds a new line
On transaction forms: the date field defaults to today — change it if entering a past transaction
On the investment transaction form: the ↓ button next to price fetches the current live price

Transaction Filters

Filters persist within a tab session but reset when you switch tabs (Income ↔ Expense)
Use the ✕ button to clear all filters at once
Date range filter: both From and To are optional — leave one blank to filter from/to open-ended

Budgets

The budget list for an empty month shows a "Copy from previous month" button — use this at the start of each month instead of re-entering all budgets
Rollover amounts appear as a blue "+rollover" badge — hover to see the exact amount

Investments

Click any row in the holdings table to go to the detail page
Ticker symbols are case-insensitive on entry (auto-uppercased on save)
The Check button on the ticker field verifies the ticker and shows the current price before you save

Reports

The "Snapshot Now" button on the Reports page saves today's net worth to the history chart — do this manually if you want more data points than the monthly automatic snapshots
CSV and Excel exports use the period currently selected in the report view

AI Assistant

The AI does not have memory between sessions — each conversation starts fresh
For best results, ask specific questions: "How much did I spend on food in March?" rather than "How am I doing?"
The context includes the last 90 days of transactions — questions about older data may not be accurate

README.md Unescape Escape

PFM — Personal Finance Manager

Table of Contents

Features Overview

Getting Started

First Login

Recommended Setup Order

Dashboard

Period Selector

Summary Cards

Cash Flow Chart

Top Spending

USD → VND Widget

AI Daily Insight

Accounts Panel

Recent Transactions

Quick Add Buttons

Transactions

Viewing Transactions

Filtering

Adding a Transaction

New Expense / Income Form Fields

AI Receipt Scanner (on new expense form)

Editing a Transaction

Deleting a Transaction

Transfers Between Accounts

Accounts

Adding an Account

Account Balances

Removing an Account

Categories

Default Categories

Adding a Category

Editing a Category

Deleting a Category

Budgets

Month Navigation

Setting a Budget

Budget Progress Bars

Unbudgeted Spending

Copy from Previous Month

Editing / Deleting a Budget

Goals & Savings

Emergency Fund Tracker

Creating a Goal

Goal Cards

Adding a Contribution

Contribution History

Completed Goals

Investments

Portfolio Overview

Adding a Holding

Ticker Format (Yahoo Finance)

Holding Detail Page

Recording a Transaction

Refreshing Prices

Removing a Holding

AI Assistant

Chat Interface

Suggested Questions

Daily Insight

Chat History

AI Model

Error States

Reports & Export

Report Types

Selecting a Period

Charts

Exporting

Settings

Profile

Changing Password

Recurring Transactions

What It Does

Creating a Rule

Managing Rules

Run Now

Upcoming Preview

CSV Import

CSV Format

README.md