Finance Module

Core financial data models for accounts, transactions, and debt tracking.

Data Models

Account

Represents any financial account (checking, savings, credit, investment).

class Account:
    name: str                    # Account name
    account_type: str           # checking, savings, credit, investment, etc.
    institution: str            # Bank/brokerage name
    account_number: str         # Last 4 digits (masked)
    current_balance: Decimal
    available_balance: Decimal
    currency: str               # USD, EUR, etc.
    is_active: bool
    external_id: str            # ID from integration source

Transaction

Individual financial transactions with categorization.

class Transaction:
    account: Account
    date: date
    description: str
    amount: Decimal             # Positive = income, Negative = expense
    category: Category
    merchant: str
    pending: bool
    external_id: str
    notes: str

Category

Transaction categorization hierarchy.

class Category:
    name: str                   # e.g., "Groceries"
    group: CategoryGroup        # e.g., "Food & Dining"
    monthly_budget: Decimal     # Optional budget limit
    is_hidden: bool

CategoryAggregate

Pre-computed monthly spending totals for fast analytics.

class CategoryAggregate:
    category: Category
    year: int
    month: int
    total_amount: Decimal
    transaction_count: int

Debt Tracking

DebtAccount

Extended information for debt accounts (mortgage, HELOC, credit cards, loans).

class DebtAccount:
    account: Account
    original_balance: Decimal
    current_balance: Decimal
    interest_rate: Decimal
    rate_type: str              # fixed, variable
    minimum_payment: Decimal
    due_day: int
    term_months: int
    payoff_date: date

InterestRateHistory

Track rate changes over time (especially for variable rates).

class InterestRateHistory:
    debt_account: DebtAccount
    rate: Decimal
    effective_date: date
    rate_type: str              # fixed, variable, promotional

DebtPayment

Individual payment breakdowns.

class DebtPayment:
    debt_account: DebtAccount
    date: date
    total_amount: Decimal
    principal_amount: Decimal
    interest_amount: Decimal
    fees_amount: Decimal

DebtPayoffScenario

Projection models for different payoff strategies.

class DebtPayoffScenario:
    name: str
    strategy: str               # avalanche, snowball, minimum
    extra_payment: Decimal
    projected_payoff_date: date
    total_interest_paid: Decimal
    total_months: int

Payoff Strategies

Strategy	Description
Avalanche	Pay highest interest rate first (mathematically optimal)
Snowball	Pay smallest balance first (psychological wins)
Minimum	Pay minimum on all (baseline comparison)

API Endpoints

Accounts

GET  /api/accounts/           # List all accounts
GET  /api/accounts/{id}/      # Get account details
GET  /api/accounts/{id}/balances/  # Balance history
POST /api/accounts/sync/      # Trigger sync

Transactions

GET  /api/transactions/       # List (paginated, filterable)
GET  /api/transactions/{id}/  # Get details
PUT  /api/transactions/{id}/  # Update (category, notes)

Debt

GET  /api/debt/accounts/      # List debt accounts
GET  /api/debt/scenarios/     # List payoff scenarios
POST /api/debt/scenarios/     # Create scenario
GET  /api/debt/projections/   # Get projections

Scheduled Tasks

Task	Schedule	Description
sync_accounts	Daily @ 6 AM	Fetch latest balances
sync_transactions_incremental	Every 30 min	New transactions
full_sync	Monthly @ 1st	Complete refresh
calculate_debt_scenarios	On change	Recalculate projections

Related

• Integrations - Data sources
• AI Agent - Spending analysis
• API Reference - Full API docs