finwise/finwise
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
521b46f6c029755a66f0beb8f6b8acaf074f8263
finwise/doc/features.md
GW_MC 2715535686 Added initial project goals and guidelines
2026-02-13 12:05:11 +00:00

26 KiB
Raw Blame History

Feature Specifications

1. Multi-Account Management

Description

Users can create and manage multiple financial accounts (bank accounts, cash, digital wallets, loans) with individual currencies and balances.

User Stories

  • As a user, I want to add multiple accounts so I can track all my finances in one place
  • As a user, I want to see a combined view of all accounts in my base currency
  • As a user, I want to archive inactive accounts without losing history
  • As a user, I want to customize account appearance with colors and icons

Features

Account Types

  1. Checking - Bank checking accounts
  2. Savings - Bank savings accounts
  3. Credit Card - Credit cards (negative balance = amount owed)
  4. Cash - Physical cash tracking
  5. Digital Wallet - PayMe, AlipayHK, WeChat Pay, Octopus, etc.
  6. Loan - Loan/liability tracking
  7. Other - Custom account types

Account Properties

  • Name (customizable)
  • Currency (ISO 4217)
  • Initial balance
  • Current balance (auto-calculated)
  • Color (hex color picker)
  • Icon (Lucide icons)
  • Include in net worth (toggle)
  • Show in combined view (toggle)

Views

  1. Combined View (default): All accounts aggregated in base currency
  2. Single Account View: Focus on one account with its transactions

Acceptance Criteria

  • User can create unlimited accounts
  • Balance updates automatically when transactions added
  • Combined view shows total net worth across selected accounts
  • Archived accounts hidden by default but accessible
  • Account deletion soft-deletes (preserves history)

2. Transaction Management

Description

Full CRUD operations for expenses, incomes, and transfers with receipt support and precise financial tracking.

User Stories

  • As a user, I want to quickly add expenses with minimal steps
  • As a user, I want to attach receipts to transactions for reference
  • As a user, I want to edit historical transactions if I made a mistake
  • As a user, I want to categorize transactions with multiple tags

Transaction Types

Expense

  • Money leaving an account
  • Required fields: account, amount, description
  • Optional: tags, merchant, notes, receipt, date

Income

  • Money entering an account
  • Same fields as expense
  • Common examples: salary, refunds, gifts

Transfer

  • Money moving between accounts
  • Auto-creates paired transactions:
    • Transfer Out (from account)
    • Transfer In (to account)
  • Supports different currencies with FX rate
  • FX rate can be auto-fetched or manually entered

Amount Handling

Tax Support

  • Gross Amount: Pre-tax amount (true spending)
  • Tax Amount: Tax portion (often 0 in Hong Kong)
  • Net Amount: Post-tax (actual paid, matches bank statement)
  • Tax Rate: Percentage stored with 8 decimal precision

Display Mode

  • Default: Show net amount (what actually left account)
  • Toggle: Show gross amount (for business expense tracking)
  • Setting: Can be changed globally or per transaction

Transaction Properties

  • Account
  • Type (expense/income/transfer)
  • Amount (gross, tax, net)
  • Currency
  • Tags (multiple)
  • Description
  • Merchant
  • Notes
  • Receipt(s)
  • Date
  • Transfer linkage (if applicable)

Editing Historical Transactions

  • Allow editing any field
  • Recalculate account balance
  • Recalculate goal contributions
  • Update reconciliation status (mark as needs review)
  • Show edit history (optional future feature)

Acceptance Criteria

  • Add transaction in < 30 seconds
  • Support multiple receipts per transaction
  • Edit any historical transaction
  • Delete with confirmation (soft delete)
  • Search by description, merchant, amount, tags
  • Filter by date range, account, type, tags

3. Tag-Based Categorization

Description

Flat tag system allowing multiple tags per transaction for flexible categorization and budgeting.

User Stories

  • As a user, I want to categorize transactions with flexible tags
  • As a user, I want to apply multiple tags to a single transaction
  • As a user, I want to set budgets for specific tags
  • As a user, I want to see spending breakdown by tags

Tag Properties

  • Name (unique)
  • Color (full color picker)
  • Icon (Lucide icon)
  • Budget amount (optional)
  • Budget period (daily/weekly/monthly/yearly)

Tag Assignment

  • Autocomplete input with tag creation
  • Multiple tags per transaction (AND relationship)
  • Quick-select recent tags
  • Visual tag chips with color and icon

System Tags (Built-in)

  • Food & Dining
  • Transportation
  • Shopping
  • Entertainment
  • Utilities
  • Health & Medical
  • Education
  • Salary
  • Investment
  • Transfer

Budgeting by Tags

  • Set budget for single tag
  • Set budget for tag combination (e.g., "Food" + "Business")
  • Track spending vs budget
  • Alert at 80% and 100% of budget

Acceptance Criteria

  • Create custom tags with full color picker
  • Apply multiple tags to one transaction
  • Filter transactions by tag(s)
  • View spending by tag over time
  • Budget alerts when approaching limit

4. Scheduled Transactions

Description

Recurring transaction templates that auto-generate on schedule with user review.

User Stories

  • As a user, I want to set up recurring bills (rent, utilities)
  • As a user, I want to schedule monthly salary entries
  • As a user, I want to review auto-generated transactions before they finalize
  • As a user, I want to skip or modify individual instances

Recurrence Patterns

Daily

  • Every N days
  • Example: Every 1 day, Every 7 days

Weekly

  • Select day(s) of week (0=Sunday, 6=Saturday)
  • Example: Every Monday and Friday

Monthly

  • Select day of month (1-31)
  • Special value: -1 = last day of month
  • Example: 1st of every month, 15th of every month

Yearly

  • Select month and day
  • Example: January 1st (annual subscription)

Custom

  • Every N days/weeks/months
  • Full flexibility

Execution Configuration

Time

  • Configurable execution time per schedule (default 00:00)
  • Stored in user's timezone
  • Converted to UTC for storage

End Conditions

  • Never: Continue indefinitely
  • After N occurrences: Stop after specific count
  • Until date: Stop on specific date

Auto-Insertion Flow

  1. Background check every minute
  2. Find schedules where next_execution_datetime <= now()
  3. Generate transaction:
    • Copy template fields
    • Set is_auto_inserted = true
    • Set needs_review = true
    • Set transaction date to execution date
  4. Update schedule:
    • Increment occurrence count
    • Calculate next execution date
    • Update next_execution_datetime
  5. Show in "Needs Review" section

User Review

  • Dashboard badge with count
  • List view of auto-inserted transactions
  • Actions:
    • Confirm: Remove needs_review flag
    • Edit: Modify any field
    • Skip: Mark instance as skipped (doesn't affect future)
    • Delete: Remove transaction

Managing Instances

  • View upcoming instances (next 30 days)
  • Skip individual instances
  • Modify schedule (affects future instances only)
  • Pause/resume schedule

Acceptance Criteria

  • Create schedules with all recurrence patterns
  • Auto-insert on schedule with configurable time
  • Mark auto-inserted as "needs review"
  • Skip individual instances without affecting pattern
  • Pause and resume schedules
  • Edit schedule (future instances only)

5. Goal Tracking

Description

Visual goal tracking with automatic contributions based on transaction rules.

User Stories

  • As a user, I want to save for a vacation with automatic contributions
  • As a user, I want to track debt payoff progress
  • As a user, I want to see visual progress toward my goals
  • As a user, I want to celebrate when I achieve a goal

Goal Types

Savings

  • Save up to target amount
  • Example: Vacation fund, emergency fund

Debt Payoff

  • Pay off debt/loan
  • Tracks reduction of liability

Spending Limit

  • Don't exceed budget
  • Tracks spending against limit

Custom

  • User-defined goal type

Goal Properties

  • Name
  • Description
  • Target amount
  • Current amount (auto-calculated)
  • Currency
  • Target date (optional)
  • Recurring (reset monthly/quarterly/yearly)
  • Linked account (optional)
  • Color
  • Icon

Auto-Contribution Rules

Rule Configuration

  • Match Condition: Transaction has ALL specified tags
  • Contribution Type:
    • Percentage: Contribute X% of transaction amount
    • Fixed: Contribute $X per transaction
  • Limits:
    • Max per transaction
    • Monthly cap

Examples

  • "Contribute 10% of all Food transactions to Vacation Fund"
  • "Contribute $5 from every Shopping transaction to Christmas Savings"
  • "Contribute 50% of Salary to Emergency Fund"

Real-Time Processing

When transaction saved:

  1. Check transaction tags
  2. Find matching goal rules
  3. Calculate contribution
  4. Update goal.current_amount
  5. Create goal_progress record
  6. Check if goal achieved
  7. Update UI immediately
  8. Show toast notification

Visual Progress

  • Circular or linear progress bar
  • Percentage complete
  • Amount remaining
  • Days until target date (if set)
  • Recent contributions list

Goal Achievement

  • Mark as achieved when current_amount >= target_amount
  • Show achievement date
  • Option to reset (for recurring goals)
  • Optional celebration animation

Manual Contributions

  • Add one-time contribution
  • Adjust current amount
  • Withdraw from goal (negative contribution)

Acceptance Criteria

  • Create goals with visual progress
  • Set up auto-contribution rules by tags
  • Real-time contribution when transaction added
  • Toast notification on contribution
  • Manual contribution/adjustment
  • Achievement tracking with celebration

6. Transfers Between Accounts

Description

Move money between accounts with automatic paired transaction creation and FX rate handling.

User Stories

  • As a user, I want to transfer between my accounts
  • As a user, I want to handle different currencies in transfers
  • As a user, I want to use custom exchange rates when needed

Transfer Flow

  1. User selects source account
  2. User selects destination account
  3. User enters amount in source currency
  4. System shows estimated destination amount using current FX rate
  5. User options:
    • Accept estimated rate
    • Enter custom rate
    • Enter exact destination amount (reverse calculate rate)
  6. Save creates paired transactions

Paired Transactions

  • Transfer Out (from account):

    • Type: transfer_out
    • Amount: source amount
    • Currency: source account currency

  • Transfer In (to account):

    • Type: transfer_in
    • Amount: destination amount
    • Currency: destination account currency

  • Linking:

    • Both transactions share same transfer_id
    • Cross-reference via related_transaction_id

Exchange Rate Handling

Auto-Fetch

  • Real-time rates from APIs:
    • HKMA (for HKD rates)
    • European Central Bank (for EUR rates)
    • Fallback: XE.com or similar
  • Cache rates for 1 hour
  • Store historical rates

Manual Entry

  • Override auto-fetched rate
  • Enter custom rate
  • Enter exact destination amount
  • Record rate source as 'manual'

Fees

  • Optional fee field
  • Deducted from source or added to destination
  • Track total cost of transfer

Same-Currency Transfers

  • Simplified flow (no FX rate needed)
  • Amount is identical in both accounts
  • Just creates paired transactions

Acceptance Criteria

  • Transfer between any two accounts
  • Support different currencies
  • Auto-fetch exchange rates
  • Allow manual rate override
  • Show transfer history
  • Edit transfer updates both transactions

7. Receipt Management

Description

Capture, store, and process receipts with OCR for automatic data extraction.

User Stories

  • As a user, I want to take photos of receipts for record keeping
  • As a user, I want OCR to extract receipt data automatically
  • As a user, I want to review and correct OCR results
  • As a user, I want to view receipts later for reference

Capture Methods

  1. Camera: Native camera access (Tauri)
  2. File Picker: Select from gallery/files
  3. Drag & Drop: Desktop web (if applicable)

Storage

  • Location: Local filesystem only
  • Path: {app_data}/receipts/{account_id}/{year}/{month}/{transaction_id}_{timestamp}.{ext}
  • Database: Store relative paths in receipt_paths JSON array
  • Retention: Keep forever (no auto-delete)
  • Security: Optional encryption at rest

OCR Processing

  • Service: Google Vision API (cloud-based, requires internet)
  • Process:
    1. Capture/Upload image
    2. Compress/optimize image
    3. Send to Vision API
    4. Extract structured data:
      • Date
      • Merchant
      • Total amount
      • Items (if available)
    5. Store raw OCR text
    6. Create transaction with extracted data
    7. Mark as "needs review"

OCR Correction UI

  • Show extracted fields
  • Allow editing before saving
  • Confidence scores (if available)
  • Manual entry fallback

Multiple Receipts

  • Support multiple images per transaction
  • Gallery view
  • Swipe between receipts
  • Delete individual receipts

Privacy & Security

  • Local only: No cloud storage of receipts
  • Encryption: Optional SQLCipher for database
  • Offline: OCR requires internet, but storage is local

Acceptance Criteria

  • Capture receipt via camera
  • Upload from file system
  • OCR extracts date, merchant, amount
  • Review and correct OCR results
  • Multiple receipts per transaction
  • View receipts in transaction detail
  • Delete receipts (permanent)

8. Reconciliation

Description

Simple account reconciliation to verify app balance matches bank statements.

User Stories

  • As a user, I want to reconcile my accounts with bank statements
  • As a user, I want to know if my records match the bank
  • As a user, I want to adjust for discrepancies

Reconciliation Process

  1. Select account to reconcile
  2. Enter statement date (period end)
  3. Enter statement ending balance
  4. System calculates app balance as of that date
  5. Shows difference (should be 0)
  6. Options:
    • Balanced: Difference is 0
    • Adjust: Create adjustment transaction
    • Review: List unreconciled transactions

Simple Approach

  • Single reconciliation record per statement
  • No line-by-line matching
  • Full trust in calculated balance
  • Adjustment transaction reconciles difference

Adjustment Transaction

  • Special transaction type: adjustment
  • Description: "Reconciliation adjustment {date}"
  • Amount: Difference (positive or negative)
  • Auto-tags: reconciliation
  • Updates account balance

Reconciliation History

  • List all reconciliations for account
  • Show date, statement balance, difference, status
  • Filter by status

Acceptance Criteria

  • Reconcile any account
  • Enter statement date and balance
  • Calculate difference automatically
  • Create adjustment transaction if needed
  • View reconciliation history
  • Mark transactions as affecting reconciliation

9. Multi-Currency Support

Description

Full multi-currency support with exchange rate tracking and conversion.

User Stories

  • As a user, I want to track accounts in different currencies
  • As a user, I want to see my total net worth in my base currency
  • As a user, I want accurate historical exchange rates for reports

Currency Handling

Supported Currencies

  • Fiat: HKD, USD, CNY, EUR, GBP, JPY, and others
  • Crypto: BTC, ETH (8 decimal support)
  • Custom: User-defined currencies

Base Currency

  • User sets one base currency
  • Combined view converts all to base currency
  • Reports use base currency

Account Currency

  • Each account has its own currency
  • Transactions stored in account's currency
  • Display shows both: "HK$ 100.00 (≈ $12.80)"

Exchange Rates

Storage

  • Daily rates stored in exchange_rates table
  • Historical rates preserved
  • 8 decimal precision

Sources

  1. Auto-fetch:

    • HKMA (Hong Kong Monetary Authority) for HKD
    • European Central Bank for EUR
    • Fallback APIs (XE.com, etc.)

  2. Manual entry:

    • User enters custom rate
    • Used for specific transactions
    • Marked as source: 'manual'

Update Frequency

  • Daily auto-fetch (background)
  • Manual refresh option
  • Store fetch timestamp

Conversion Logic

Real-time Conversion

  • Use most recent rate for current conversions
  • Show rate date in UI

Historical Conversion

  • Use rate from transaction date
  • Accurate for historical reports

Display Format

Amount: HK$ 1,234.56789012
Rate: 7.84950000 (2026-02-13)
Converted: $157.28000000

Acceptance Criteria

  • Multiple currencies per user
  • Set base currency for combined view
  • Auto-fetch daily exchange rates
  • Manual rate entry for transactions
  • Historical rate tracking
  • Display converted amounts in real-time

10. Backup & Export

Description

JSON-based backup and restore functionality.

User Stories

  • As a user, I want to backup my data to a file
  • As a user, I want to restore from a backup
  • As a user, I want to transfer data to a new device

Export

  • Format: JSON with checksum
  • Content: All tables (accounts, transactions, goals, etc.)
  • Compression: Optional ZIP
  • Location: User-selected folder
  • Encryption: Optional password protection

Import

  • Validation: Verify checksum and schema version
  • Merge or Replace:
    • Replace: Clear database, import all
    • Merge: Import new records, update existing by ID
  • Conflict Resolution: Last-write-wins or manual merge
  • Progress: Show import progress for large datasets

Auto-Backup (Optional)

  • Periodic automatic export
  • User selects folder and frequency
  • Keep last N backups

Migration Support

  • Schema version check
  • Automatic migration if possible
  • Manual guidance if incompatible

Acceptance Criteria

  • Export all data to JSON
  • Import from JSON file
  • Verify data integrity with checksum
  • Optional password encryption
  • Show export/import progress
  • Handle schema version differences

11. Internationalization (i18n)

Description

Multi-language support with English and Traditional Chinese.

Supported Languages

  • English (en) - Primary
  • Traditional Chinese (zh-Hant) - 繁體中文

Language Selection

  • Auto-detect from system
  • Manual override in settings
  • Persist selection

Translated Content

  • All UI labels and buttons
  • Error messages
  • Date/time formats
  • Currency display formats
  • Category/tag names (user-defined tags in user's language)

RTL/LTR

  • Both languages LTR (no RTL support needed)

Acceptance Criteria

  • Switch language in settings
  • All UI text translated
  • Proper date/time localization
  • Currency format per locale
  • Persist language preference

12. Settings & Preferences

Description

User-configurable settings for personalization.

Settings Categories

General

  • Language (en/zh-Hant)
  • Default currency
  • Base currency for combined view
  • Timezone (auto/manual)

Display

  • Default view (combined/single)
  • Display mode (net/gross amounts)
  • Decimal places (2-8)
  • Date format (YYYY-MM-DD, DD/MM/YYYY, etc.)
  • Time format (12h/24h)
  • Week starts on (Sunday/Monday)

Appearance

  • Theme (light/dark/system)
  • Accent color
  • Font size

Data

  • Auto-backup toggle
  • Backup frequency
  • Backup location
  • Export data
  • Import data

Scheduled Transactions

  • Check interval (minutes)
  • Default execution time
  • Notification preferences (future)

About

  • App version
  • Build number
  • Open source licenses
  • Privacy policy
  • Terms of use

Acceptance Criteria

  • All settings persist across sessions
  • Immediate UI updates on setting change
  • Reset to defaults option
  • Import/export settings (optional)

Future Features (Post-MVP)

Notifications

  • Scheduled transaction reminders
  • Budget alerts
  • Goal achievement
  • Bill due dates

Cloud Sync

  • Multi-device synchronization
  • Conflict resolution UI
  • End-to-end encryption

Advanced Analytics

  • Spending trends
  • Cash flow forecasting
  • Net worth over time
  • Category trends

Investment Tracking

  • Stock portfolios
  • Real-time prices
  • Gain/loss calculations

Bill Management

  • Bill reminders
  • Recurring bill tracking
  • Payment history

Bank Import

  • HSBC Open Banking API
  • Hang Seng API
  • OFX/QFX file import
  • CSV import with mapping

Reports

  • PDF export
  • Tax reports
  • Custom date ranges
  • Scheduled reports

Shared Accounts

  • Family/partner sharing
  • Permission levels
  • Activity log
Reference in New Issue View Git Blame Copy Permalink