Finance Debts

How debts (credit cards, installment loans, and other liabilities) are modeled, the per-type validation and amortization rules, and how clients call the debts API.

Overview

A debt is a per-user record of an outstanding balance with an APR, optional minimum payment and due day, and an optional link to an Account. The server validates per-type constraints (credit card vs. installment loan vs. other), computes amortization schedules and payoff projections, and reflects debt payments as EXPENSE transactions tagged to the debt. Debts are soft-deleted (Status.INACTIVE) and excluded from list / progress / summary queries.

Three debt types are supported, each with different required fields and progress semantics:

Architecture

Clients call REST endpoints. DebtService is the source of truth for per-type rules and payoff math; TransactionService calls back into DebtService.applyTransactionPayment / revertTransactionPayment whenever a debt-linked transaction is created, updated, or deleted.

Data model

debts table (Exposed UUIDTable, Debt.kt):

Transactions tagged to a debt carry a nullable debt_id FK with SET_NULL on delete. The link is only valid for EXPENSE transactions in the DEBT category (enforced by DebtService.isValidDebtLink).

The base table is created by JdbcSchemaBootstrap via Exposed SchemaUtils. Subsequent column changes ship as Flyway migrations:

• V22__debt_type_and_credit_limit.sql — adds debt_type (NOT NULL DEFAULT 'INSTALLMENT_LOAN') and credit_limit.
• V23__debt_interest_rate_precision.sql — widens interest_rate from DECIMAL(5,4) to DECIMAL(6,3) so APR can be stored as a percentage instead of a fraction.

Per-type rules

Centralized in DebtTypeRules. Both create and update paths go through validateCreate / validateUpdate; failures throw IllegalArgumentException → 400 Bad Request with the message in ErrorResponse.

Amortization & payoff

All payoff math lives in DebtAmortizationCalculator. MAX_PERIODS = 600 caps the projection at 50 years.

• generateSchedule returns ScheduleResult { entries, totalInterest, payoffDate, paymentTooLow }. paymentTooLow is set when the monthly payment fails to cover monthly interest or the 600-period cap is hit.
• computeProgress is what /finance/debts/{id}/progress (and getAllWithProgress) returns: derived percentagePaid, monthsRemaining, totalInterestRemaining, paymentTooLow. If monthlyPayment is null, it falls back to estimateMinimumPayment.
• estimateMinimumPayment — 60-month standard amortization formula when APR > 0; otherwise balance / 60 floored at $1.
• firstPaymentDate(reference, dueDayOfMonth) — clamps dueDayOfMonth to 1..28 and returns the next occurrence on/after reference.

Payment recording & balance sync

Two side-effect-heavy paths cross-link debts with transactions and accounts:

• POST /finance/debts/{id}/payment — creates an EXPENSE transaction in the DEBT category linked to the debt. DebtRepository.recordPayment defers to TransactionRepository, which in turn calls DebtService.applyTransactionPayment to reduce current_balance. Deleting or unlinking the transaction reverts the balance change via revertTransactionPayment.
• POST /finance/debts/{id}/sync-balance — only meaningful for credit cards with an account_id. Reads the linked account’s balance (computed via AccountBalanceCheckpointService — see accounts.md) and maps it to current_balance via DebtTypeRules.mapAccountBalanceToDebtBalance. For credit cards this means a negative account balance becomes a positive owed amount.

API

All routes are under route("/finance") { route("/debts") { … } } in FinanceRouting.kt:939-1089. Authentication: LoggedUserDTO principal; every route filters by userId.

Key DTOs (defined in FinanceDTOs.kt:139-220):

• CreateDebtDTO — all fields optional except name and type; defaults: type=INSTALLMENT_LOAN, originalPrincipal=0.0, interestRate=0.0.
• UpdateDebtDTO — every field nullable plus clearAccountId: Boolean = false.
• DebtResponseDTO — flat read shape: id, name, type, principals/balances, APR, minimum, dueDay, targetPayoffDate, accountId.
• DebtProgressResponseDTO — wraps DebtResponseDTO and adds percentagePaid, remainingAmount, estimatedPayoffDate, monthsRemaining, totalInterestRemaining, paymentTooLow, utilizationPercentage.
• AmortizationEntryDTO — period, date (DD/MM/YYYY), payment, principal, interest, remainingBalance.
• DebtAmortizationScheduleResponseDTO — debtId, monthlyPayment, entries[], totalInterest, payoffDate, paymentTooLow.
• RecordDebtPaymentDTO — amount, accountId, optional description, optional date (defaults to today in the server’s default timezone, formatted DD/MM/YYYY).

Client mapping

Compose i18n: shared/src/commonMain/composeResources/values/strings.xml:638-674 (en) + matching keys in values-es/strings.xml.

Known gaps

• Web frontend has no debt UI. FinanceTab in web-frontend/src/app/[locale]/finance/page.tsx:137 is 'ACCOUNTS' | 'TRANSACTIONS' | 'SCHEDULED' | 'BUDGETS' | 'STATISTICS' | 'PREDICTION' — DEBTS is missing. lib/api/finance.ts has no Debt types or financeApi.* methods. DEBT only appears as a transaction-category string. (Distinct concept from the new debt feature.)
• No reminders. due_day_of_month is stored and used in payoff math but never surfaces as a notification, calendar entry, or dashboard alert. The notifications infra exists (NotificationDispatcher, NotificationType, NotificationThrottleService, the ScheduledTransactionCheckerService background-loop pattern) but isn’t wired for debts. (calendar/* modules in the repo contain only build artifacts, so a calendar entry is not a viable target today.)
• No aggregate summary. No “total debt” / “weighted avg APR” / “next 3 due dates” endpoint or summary card. Clients can derive most of it from the list but don’t.
• No payoff-strategy planner (Avalanche / Snowball). Listed in Roadmap §148 (“Debt payoff scenarios”) but not implemented.
• paymentTooLow warning is buried. Surfaces only inside the expanded amortization panel in DebtItem; not visible on the debt list summary.
• Amortization is table-only. No chart visualization (balance over time, principal vs interest). recharts is available on web; Compose currently has only the desktop-side BalanceChart Canvas precedent.
• No bulk import / export. No CSV import for existing debts and no schedule export.

Testing

• Unit (per-type rules): DebtTypeRulesTest — covers credit-card limits, loan principal, account-type pairing, utilization, APR bounds.
• Unit (amortization): DebtAmortizationCalculatorTest — zero balance, zero APR paydown, typical loan, payment-too-low detection, payoff completion.
• DB integration: DebtSyncBalanceTest — exercises the credit-card account → debt balance sync end-to-end.

No client tests yet for debt UIs.