Finance Feature Guide

Comprehensive guide to the Finance module: accounts, transactions, budgets, savings goals, scheduled transactions, and the balance prediction engine.

Overview

The Finance module is the most complex feature in Oter. It provides full personal finance management — tracking income, expenses, and transfers across multiple accounts — plus a sophisticated balance prediction engine that projects future account balances using historical data, scheduled transactions, periodic spends, and configurable noise/scenarios. The module follows Clean Architecture on Android (three Gradle modules) and shares its HTTP client and models via the KMP shared layer.

Architecture

The finance feature spans five layers: Android presentation, Android domain, Android data, KMP shared services, and the Ktor server.

Data flows unidirectionally: UI intent → ViewModel → UseCase → Repository → DataSource → HTTP → Server.

ViewModel Structure

The presentation layer uses one ViewModel per domain concept, coordinated by a shared wrapper.

Each ViewModel is responsible for a single domain. FinanceActionsWrapper delegates actions to the right ViewModel. FinanceStateConverter merges all individual states into the single DesktopFinanceState consumed by the UI.

Data Models

Key Enums

TransactionType: INCOME, EXPENSE, TRANSFER

AccountType: CHECKING, SAVINGS, CREDIT_CARD, INVESTMENT, CASH, LOAN, OTHER

Category: 30+ values grouped as income (SALARY, INVESTMENT, FREELANCE, GIFT) and expense (FOOD, HOUSING, TRANSPORTATION, SHOPPING, HEALTH, SUBSCRIPTION, …)

CategoryVolatilityType (used by prediction engine):

API Endpoints

Accounts

See accounts.md for balance derivation, soft-delete, client mapping, and tests.

Transactions

Budgets

Savings Goals

Scheduled Transactions

Category Keywords & Analytics

Balance Prediction Engine

The prediction engine is the core differentiator of the Finance module. It generates time-series balance projections across three scenarios.

Inputs and Scenarios

Each prediction point in the response represents one date and includes its balance, individual transactions, and per-scenario balances for that date.

Scenario lab (what-if)

Persisted balance scenarios and session inline adjustments layer on top of the core engine. See balance-prediction-scenario-lab.md for adjustment types, affordability verdicts, desktop UI, and platform coverage.

Desktop UI (composeApp/.../balanceprediction/): scenarios drawer, adjustment dialog, affordability dialog, budget impact on point details, baseline dashed line on chart. Category fields use CategoryDropdown (enum-backed).

Safety Features

Pagination

Prediction results are paginated (default 100 points/page) to handle long date ranges efficiently. Clients specify page and pageSize in BalancePredictionFilters.

Client Behavior

For long date ranges, the UI may request additional pages by incrementing filters.page.

Key Files

Testing

• Unit tests should cover BalancePredictionViewModel scenario switching and state transitions.
• Domain tests should cover use case edge cases: empty account list, zero balance, date range spanning month boundaries.
• Repository tests should verify Result.failure propagation when the HTTP layer returns an error.
• Server tests should cover the prediction engine with mocked scheduled/historical transactions; verify danger events are emitted when safetyFloor is breached.

Troubleshooting

Prediction returns empty points

• Verify fromDate < toDate in BalancePredictionFilters.
• Check that at least one accountId is valid and belongs to the authenticated user.
• Confirm pageSize > 0 and page >= 0.

Budget progress not updating

• Ensure the transaction category matches the budget’s category exactly.
• Check startDate/endDate overlap between the transaction date and the budget period.

Transaction import assigns wrong categories

• Check category-keywords for the relevant category — add or update keywords as needed.
• Use the preview endpoint before confirming an import to inspect auto-categorization results.

Scheduled transactions not appearing in prediction

• Verify includeScheduledTransactions: true in BalancePredictionFilters.
• Confirm the scheduled transaction’s startDate falls within the prediction date range.

Related Docs

• Prediction engine — deep-dive into the balance prediction algorithm
• balance-prediction-scenario-lab.md — scenario lab, affordability, desktop UI
• Domain & models — cross-feature domain model reference
• Global architecture — how finance fits into the overall system architecture