💰 Finance & Budgeting Services

18 services covering expense tracking, budgeting, debt management, investments, forecasting, and financial calculators — all with offline-first local persistence.

ExpenseTrackerService

The central expense tracking engine. Records income and expense transactions with categories, payment methods, tags, and notes. Provides daily summaries, category breakdowns, budget alerts, and streak tracking.

Key Types

enum ExpenseCategory { food, transport, housing, utilities, entertainment,
    shopping, health, education, travel, income, other }

enum PaymentMethod { cash, credit, debit, bankTransfer, digital, other }

class BudgetConfig {
  final double monthlyBudget;          // Default: 3000.0
  final Map<ExpenseCategory, double> categoryLimits;
  final double alertThreshold;          // 0.0–1.0, default 0.8
  final String currencySymbol;
}

class DailyExpenseSummary {
  final DateTime date;
  final double totalSpent;
  final double totalIncome;
  final int transactionCount;
  final Map<ExpenseCategory, double> byCategory;
  final Map<PaymentMethod, double> byPaymentMethod;
  double get netFlow;                   // income - spending
}

Core Methods

BudgetPlannerService

Monthly budget allocation with category-level caps. Compares planned budgets against actual spending from ExpenseTrackerService to surface variances and savings rates.

Core Methods

SavingsGoalService

Named savings goals (vacation, emergency fund, etc.) with individual contribution tracking, progress percentages, and monthly savings insights.

Core Methods

DebtPayoffService

Debt management with payoff strategy simulation. Extends CrudService<DebtEntry> for CRUD operations and adds snowball/avalanche payoff planning.

Payoff Strategies

enum PayoffStrategy {
  snowball,    // Smallest balance first (behavioral motivation)
  avalanche,   // Highest interest rate first (mathematically optimal)
}

Core Methods

NetWorthTrackerService

Track assets and liabilities across accounts with monthly net worth snapshots, milestones, and category breakdowns.

Core Methods

FireCalculatorService

Financial Independence / Retire Early (FIRE) calculator. Projects portfolio growth over time and estimates the year you can retire based on savings rate, investment returns, and withdrawal strategy.

Core Methods

FireResult

class FireResult {
  final int yearsToFire;               // Years until financial independence
  final double fireNumber;             // Target portfolio value
  final double savingsRate;            // Annual savings as % of income
  final List<FireProjectionYear> projections;  // Year-by-year portfolio growth
}

Withdrawal Strategies

// Pre-defined withdrawal rates
WithdrawalStrategy.traditional  // 4% rule (Trinity Study)
WithdrawalStrategy.conservative // 3.5% (longer retirement horizon)
WithdrawalStrategy.lean         // 3% (lean FIRE)
WithdrawalStrategy.fat          // 4.5% (fat FIRE with margin)

ExpenseForecastService

Analyzes expense history to detect spending anomalies, identify recurring expenses, forecast upcoming costs, and generate budget alerts.

Core Methods

ForecastReport Contents

class ForecastReport {
  final List<CategoryForecast> forecasts;       // Per-category projections
  final List<SpendingAnomaly> anomalies;         // Unusual spending spikes
  final List<RecurringExpense> recurring;         // Detected recurring charges
  final List<BudgetAlert> alerts;                // Budget threshold warnings
  final double projectedMonthlyTotal;
}

SubscriptionTrackerService

Manage recurring subscriptions with billing cycle tracking, renewal calendars, and spending breakdowns by category.

Core Methods

BillReminderService

Track bills with due dates, autopay status, and payment confirmation. Extends CrudService<BillEntry>.

Core Methods

CompoundInterestService

Compound interest projections with configurable compounding frequencies. Stateless — all methods are const-constructable and pure.

Compounding Frequencies

CompoundFrequency.annually     // 1×/year
CompoundFrequency.semiAnnually // 2×/year
CompoundFrequency.quarterly    // 4×/year
CompoundFrequency.monthly      // 12×/year
CompoundFrequency.daily        // 365×/year

Core Methods

LoanCalculatorService

Loan amortization calculator with full payment schedules and extra-payment analysis. Shows interest savings from additional payments.

Core Methods

LoanResult

class LoanResult {
  final double monthlyPayment;
  final double totalInterest;
  final double totalPaid;
  final List<AmortizationEntry> schedule;  // Month-by-month principal/interest split
}

MortgageCalculatorService

Mortgage-specific calculator with property tax, PMI, HOA, and insurance factored into the monthly payment. Includes home affordability estimation.

Core Methods

TaxCalculatorService

US federal income tax calculator with 2024 tax brackets, standard/itemized deductions, and filing status support.

Filing Statuses

FilingStatus.single
FilingStatus.marriedJoint
FilingStatus.marriedSeparate
FilingStatus.headOfHousehold

Core Methods

TaxResult

class TaxResult {
  final double taxableIncome;
  final double totalTax;
  final double effectiveRate;           // totalTax / grossIncome
  final double marginalRate;            // Top bracket rate
  final List<BracketBreakdown> brackets; // Tax owed per bracket
}

SalaryCalculatorService

Gross-to-net salary calculator with federal tax withholding, FICA (Social Security + Medicare), and state tax estimation.

Core Methods

SalaryResult

class SalaryResult {
  final double grossAnnual;
  final double federalTax;
  final double stateTax;
  final double socialSecurity;
  final double medicare;
  final double netAnnual;
  final double netMonthly;
  final double netBiweekly;
}

InvoiceService

Invoice calculation engine with line items, quantity pricing, tax rates, and discount application.

Core Methods

CurrencyConverterService

Offline currency converter with 30+ built-in exchange rates (pegged to USD). Rates are approximate — intended for estimation, not trading.

Core Methods

TipCalculatorService

Simple tip calculator with bill splitting. Calculates tip amount, total per person, and supports custom tip percentages.

Core Methods

Service Relationships

The finance services form a connected ecosystem:

ExpenseTrackerService ──→ BudgetPlannerService  (actual vs planned)
         │                        │
         ├──→ ExpenseForecastService  (anomaly detection, projections)
         │
         └──→ SavingsGoalService  (track money set aside)
                    │
                    └──→ FireCalculatorService  (retirement projections)
                              │
CompoundInterestService ──────┘  (investment growth math)

DebtPayoffService ←──→ LoanCalculatorService  (shared amortization logic)
         │
MortgageCalculatorService  (extends loan concepts)

SubscriptionTrackerService ──→ BillReminderService  (recurring obligations)

TaxCalculatorService ──→ SalaryCalculatorService  (tax brackets shared)

InvoiceService, CurrencyConverterService, TipCalculatorService  (standalone utilities)

Last updated: April 2026 · GitHub