Skip to Content
OverviewDomain & models

Domain & Models

Reference for core domain concepts and shared data models used across all features, with emphasis on the financial prediction system.

This document describes the core domain concepts and data models used in Oter, with a focus on the financial prediction system.

Core Domain Concepts

Transaction

A Transaction represents a single financial movement (income, expense, or transfer) in a user’s account.

Key Fields:

  • id: Unique identifier
  • amount: Transaction amount (always positive)
  • type: Transaction type (INCOME, EXPENSE, TRANSFER)
  • category: Spending category (FOOD, TRANSPORT, ENTERTAINMENT, etc.)
  • accountId: Associated account
  • description: Human-readable description
  • date: Transaction date
  • frequency: Optional recurrence pattern (for recurring transactions)

Business Rules:

  • Amount must be non-negative
  • Date cannot be in the future (for committed transactions)
  • TRANSFER type transactions don’t affect total balance (they move money between accounts)
  • Category must be valid for the transaction type

Usage: Transactions form the historical data foundation for balance predictions. The prediction engine analyzes patterns in transaction history to project future behavior.

ScheduledTransaction

A ScheduledTransaction represents a recurring financial event that will occur in the future.

Key Fields:

  • id: Unique identifier
  • amount: Transaction amount
  • type: Transaction type (INCOME or EXPENSE)
  • category: Spending category
  • accountId: Associated account
  • description: Description
  • startDate: When the schedule begins
  • frequency: Recurrence frequency (DAILY, WEEKLY, MONTHLY, YEARLY)
  • interval: Frequency interval (e.g., every 2 weeks = frequency WEEKLY, interval 2)
  • applyAutomatically: Whether to automatically create transactions

Business Rules:

  • Start date must be in the future or today
  • Frequency and interval must be valid combinations
  • Only INCOME and EXPENSE types are supported (no TRANSFER)
  • When applyAutomatically is true, transactions are created automatically on schedule

Usage: Scheduled transactions are projected forward in time during balance prediction, generating expected transactions for each occurrence within the prediction period.

Account

An Account represents a financial account (checking, savings, credit card, etc.).

Key Fields:

  • id: Unique identifier
  • name: Account name
  • type: Account type (CHECKING, SAVINGS, CREDIT_CARD, INVESTMENT, CASH, LOAN, OTHER)
  • balance: Current balance
  • initialBalance: Starting balance when account was created
  • currency: Currency code (default: USD)
  • isArchived: Client-side UI flag (not persisted on server; server uses soft-delete via Status.DELETED)

Business Rules:

  • Account name uniqueness per user is documented but not enforced server-side
  • Balance = initialBalance + sum of signed ACTIVE transactions (INCOME +, EXPENSE -, TRANSFER +amount as stored)
  • Soft-deleted accounts are excluded from list, get, and total-balance; clients may also filter isArchived
  • Currency must be a valid ISO 4217 code

See Accounts for API and implementation details.

Usage: Accounts are the containers for transactions. Balance predictions are calculated per account, and can aggregate multiple accounts for total balance projections.

Budget

A Budget represents a spending limit for a specific category over a time period.

Key Fields:

  • id: Unique identifier
  • name: Budget name
  • amount: Budget amount
  • category: Spending category this budget applies to
  • startDate: Budget start date
  • endDate: Optional end date (null = ongoing)
  • frequency: Recurrence frequency (for recurring budgets)
  • rollover: Whether unused amount rolls over to next period
  • rolloverAmount: Maximum rollover amount

Business Rules:

  • Budget amount must be positive
  • Start date must be before end date (if end date provided)
  • Category must be a valid expense category
  • Rollover amount cannot exceed budget amount

Usage: Budgets help users track spending against limits. The prediction engine can incorporate budget constraints into projections.

SavingsGoal

A SavingsGoal represents a financial target the user wants to achieve.

Key Fields:

  • id: Unique identifier
  • name: Goal name
  • targetAmount: Target amount to save
  • currentAmount: Current progress toward goal
  • targetDate: Optional target date
  • accountId: Associated account
  • isCompleted: Whether goal has been reached
  • monthlyContribution: Planned monthly contribution

Business Rules:

  • Target amount must be positive
  • Current amount cannot exceed target amount (unless goal is completed)
  • Target date must be in the future (if provided)
  • Monthly contribution must be non-negative

Usage: The prediction engine can analyze whether goals will be met based on current projections, calculating required monthly contributions if needed.

BalancePredictionFilters

Configuration for generating balance predictions.

Key Fields:

  • fromDate: Start date for prediction
  • toDate: End date for prediction
  • accountIds: Optional list of account IDs to include (null = all accounts)
  • includeScheduledTransactions: Whether to include scheduled transactions
  • includePastMonthBehavior: Whether to replicate past month’s transactions
  • periodicSpends: List of periodic spending patterns (also converted to NEW_TRANSACTION adjustments when scenario lab is active)
  • scenarioIds: Saved balance scenario UUIDs to merge into the run
  • inlineAdjustments: Session-only ScenarioAdjustment list (NEW_TRANSACTION, MODIFY_CATEGORY, MODIFY_SCHEDULED)
  • compareToBaseline: When true, response includes baselinePoints without scenario/inline layer
  • noisePercentage: Optional noise percentage (e.g., 5.0 for ±5% variation)
  • granularity: Prediction granularity (DAILY, WEEKLY, MONTHLY)
  • safetyFloor: Minimum balance threshold for alerts
  • overdraftThreshold: Overdraft threshold (typically 0.0)
  • goalId: Optional goal to analyze
  • baseAmount: Optional starting balance override
  • page: Pagination page number
  • pageSize: Results per page

Business Rules:

  • From date must be before or equal to to date
  • Noise percentage must be between 0 and 100 (if provided)
  • Page and page size must be non-negative
  • Safety floor and overdraft threshold are optional but recommended

Usage: Filters control all aspects of prediction generation, from date ranges to scenario configuration.

BalancePredictionPoint

A single point in a balance prediction time series.

Key Fields:

  • date: Prediction date
  • balance: Base balance at this date
  • transactions: List of transactions affecting this date
  • scenarios: Optional scenario balances (optimistic, pessimistic, base)

Business Rules:

  • Date must be within prediction range
  • Balance can be negative (overdraft)
  • Transactions list includes all transactions affecting this date

Usage: Each point represents the projected balance and transactions for a specific date. Multiple points form a time series showing balance evolution over time.

BalancePredictionResponse

Complete response from the prediction engine.

Key Fields:

  • points: List of balance prediction points (paginated)
  • startingBalance: Starting balance at prediction start
  • endingBalance: Ending balance at prediction end
  • minBalance: Minimum balance across all scenarios
  • maxBalance: Maximum balance across all scenarios
  • safeToSpendToday: Calculated safe-to-spend amount
  • dangerEvents: List of dates where balances fall below thresholds
  • goalAnalysis: Optional goal analysis results
  • categoryForecasts: Projected spending by category
  • budgetImpact: Per-budget (and unbudgeted) baseline vs scenario spend with verdict
  • baselinePoints: Optional baseline curve when compareToBaseline is true
  • compareToBaseline: Whether baseline points were requested
  • Pagination: totalPoints, currentPage, totalPages, pageSize

Business Rules:

  • Points are sorted by date ascending
  • Pagination metadata must match actual results
  • Danger events are sorted by date

Usage: The complete prediction result, including all calculated metrics and analyses.

Transaction Types

INCOME

Money received (salary, freelance income, gifts, etc.). Increases account balance.

EXPENSE

Money spent (purchases, bills, subscriptions, etc.). Decreases account balance.

TRANSFER

Money moved between accounts. Does not affect total balance across all accounts, but affects individual account balances.

Category System

Categories are predefined and organized by type:

Expense Categories:

  • FOOD, GROCERIES, RESTAURANT
  • TRANSPORT, GAS, PUBLIC_TRANSPORT
  • ENTERTAINMENT, SUBSCRIPTIONS
  • SHOPPING, CLOTHING
  • BILLS, UTILITIES, RENT
  • HEALTH, INSURANCE
  • EDUCATION, PERSONAL_CARE
  • TRAVEL, GIFTS
  • OTHER

Income Categories:

  • SALARY, FREELANCE, INVESTMENT
  • GIFT, REFUND
  • OTHER

Categories are used for:

  • Transaction classification
  • Budget assignment
  • Spending analysis
  • Category-level forecasting

Frequency Patterns

Recurring transactions and budgets use frequency patterns:

  • DAILY: Every day
  • WEEKLY: Every week (with optional interval, e.g., every 2 weeks)
  • MONTHLY: Every month
  • YEARLY: Every year

Frequency patterns are combined with intervals to support complex schedules (e.g., “every 2 weeks”, “every 3 months”).

Scenario Types

Balance predictions support multiple scenarios:

  • BASE: Standard projection using configured parameters
  • OPTIMISTIC: Best-case outcomes with favorable noise variations
  • PESSIMISTIC: Worst-case outcomes with unfavorable noise variations

Each scenario provides independent balance projections, allowing users to understand the range of possible outcomes.

Global architecturePrediction engine