nngo/Personal-Finance-Management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

05/31 Update documents

Browse Source
This commit is contained in:
nngo
2026-05-31 17:28:50 -04:00
parent 5983794217
commit 8b1594da5a
3 changed files with 1249 additions and 626 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+689 -2
View File
@@ -1,3 +1,690 @@
# Personal-Finance-Management
# PFM — Personal Finance Manager
Personal-Finance-Management system
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
---
## Table of Contents
1. [Features Overview](#features-overview)
2. [Getting Started](#getting-started)
3. [Dashboard](#dashboard)
4. [Transactions](#transactions)
5. [Accounts](#accounts)
6. [Categories](#categories)
7. [Budgets](#budgets)
8. [Goals & Savings](#goals--savings)
9. [Investments](#investments)
10. [AI Assistant](#ai-assistant)
11. [Reports & Export](#reports--export)
12. [Settings](#settings)
13. [Recurring Transactions](#recurring-transactions)
14. [CSV Import](#csv-import)
15. [Receipt OCR](#receipt-ocr)
16. [USD → VND Rate Widget](#usd--vnd-rate-widget)
17. [Keyboard Shortcuts & Tips](#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
### First Login
1. Navigate to `https://pfm.ngodanguyen.tech`
2. Enter the username and password created during setup (`python scripts/init_db.py`)
3. Check "Remember me" to stay logged in across browser sessions
### Recommended Setup Order
1. **Add accounts** — add your bank accounts, cash wallet, and credit cards first (Settings sidebar → Accounts)
2. **Review categories** — default categories are already seeded; add custom ones if needed
3. **Set your currency** — go to Settings → Profile and set your app currency (USD, VND, etc.)
4. **Add transactions** — start entering income and expenses
5. **Set budgets** — once you have categories, set monthly limits
6. **Create goals** — add savings goals and start contributing
7. **Add investments** — track your portfolio holdings
8. **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.
### USD → VND Widget
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](#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](#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.
---
## Categories
Navigate via the sidebar footer → **Categories**.
Two panels: **Expense Categories** (left) and **Income Categories** (right).
### Default Categories
**Expense (14):** Housing, Food & Dining, Transport, Utilities, Health, Entertainment, Shopping, Education, Insurance, Personal Care, Travel, Subscriptions, Gifts, Other
**Income (7):** Salary, Freelance, Business, Investment, Rental, Gift Received, Other Income
System categories (marked with a grey "system" badge) cannot be deleted but can be edited (color and icon only — name is protected).
### Adding a Category
Click **+Expense** or **+Income** in the topbar. Set a name, type, color (click a swatch), and icon (click an icon swatch).
**Category type options:**
- **Expense** — appears only in expense transaction dropdown
- **Income** — appears only in income transaction dropdown
- **Both** — appears in both dropdowns
### Editing a Category
Click **Edit** next to any category. Color and icon can always be changed. Name can only be changed for non-system categories.
### Deleting a Category
Click **Del** next to a non-system category. Categories with existing transactions cannot be hard-deleted — they are deactivated (hidden) instead. A warning message explains this.
---
## Budgets
Navigate via **Budgets** in the sidebar.
### Month Navigation
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.
### Suggested Questions
Eight suggestion buttons appear on the right panel. Click any to fill the chat input:
- "Where did I overspend this month?"
- "How is my budget looking?"
- "Am I on track for my goals?"
- "What's my biggest expense category?"
- "Summarize my finances"
- "How can I save more?"
- "What's my net worth trend?"
- "Review my investments"
### 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
1. Choose your CSV file
2. Select a **Default Account** — used when the account column is missing or the name doesn't match any of your accounts
3. Check **Skip duplicate transactions** (recommended) — skips rows where date + description + amount + type exactly match an existing transaction
4. Click **Preview Import**
5. 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)
6. 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:
1. **Drag and drop** a receipt image onto the panel, OR click the panel to browse for a file
2. Accepted formats: JPG, PNG, GIF, WEBP (max 10MB — PDF not supported for OCR)
3. The panel shows a spinning animation while scanning
4. 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
5. Review all fields before clicking Save — OCR is not perfect, especially on low-quality photos
6. 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
---
## USD → VND Rate Widget
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
1. **Primary:** Yahoo Finance forex (`USDVND=X` via yfinance) — most reliable
2. **Fallback:** ExchangeRate API (`open.er-api.com`) — free, no key required
3. **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
### Navigation
- 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