Overview
This document describes the mathematical formulas, assumptions, and implementation details for all 12 Money.Holdings calculators. Each calculator is implemented in pure TypeScript in src/calculators/ with comprehensive unit tests.
All calculations run client-side. Results are deterministic (except Monte Carlo) and reproducible given the same inputs. Rounding follows financial conventions: 2 decimal places for currency, 4 for rates, with banker's rounding for intermediate steps.
Shared Conventions
- Rounding:
round2(x) = Math.round(x * 100) / 100, round4(x) = Math.round(x * 10000) / 10000 - Monthly Rate:
r = annualRate / 100 / 12 - Periods: Monthly unless otherwise specified
- Day Count: 30/360 for monthly, Actual/365 for daily
- Annuity Due vs. Ordinary: Configurable per calculator
- Inflation Adjustment: Real value = Nominal / (1 + inflation)^years
1. Mortgage Payment
Formula
M = P * r * (1 + r)^n / ((1 + r)^n - 1) Where: P = Principal (loan amount) r = Monthly interest rate (annualRate / 12 / 100) n = Total payments (termYears * 12) M = Monthly payment
Amortization Schedule
- Interest = Remaining Balance × r
- Principal = M - Interest
- New Balance = Previous Balance - Principal
- Extra payment applied entirely to principal
PMI
Estimated at 0.5%–1% of loan annually if LTV > 80%. Not included in base payment.
Sources
- CFPB Regulation Z (Truth in Lending)
- Fannie Mae Single Family Selling Guide
- Standard mortgage mathematics (Fabozzi, "Fixed Income Mathematics")
2. Compound Interest
Formula (with contributions)
FV = P(1 + r)^n + PMT × [((1 + r)^n - 1) / r] × (1 + r × timing) Where: P = Principal r = Rate per period (annualRate / compoundingFrequency / 100) n = Total periods (years × compoundingFrequency) PMT = Contribution per period timing = 0 (end/ordinary) or 1 (begin/annuity due)
Effective Annual Rate
EAR = (1 + nominalRate / m)^m - 1
Inflation Adjustment
RealFV = NominalFV / (1 + inflationRate)^years
Sources
- Bodie, Kane, Marcus "Investments" Ch. 5
- IRS Publication 590-A (IRA contribution limits context)
- Standard time value of money formulas
3. Loan Payment
Same formula as Mortgage Payment. Supports any term in months.
Extra Payments
- Recalculates remaining term after each extra payment
- Interest saved = Standard total interest - Actual total interest
4. Amortization Schedule
Detailed period-by-period output of the standard amortization formula.
Payment Frequencies
- Monthly: 12 periods/year, rate = annual/12
- Biweekly: 26 periods/year, rate = annual/26, payment = monthly/2
- Weekly: 52 periods/year, rate = annual/52, payment = monthly × 12/52
Sources
- Consumer Financial Protection Bureau amortization examples
- UK FCA MCOB 10A (annual percentage rate calculation)
5. Mortgage Overpayment
Method
- Simulates standard amortization vs. amortization with extra principal
- Compares total interest, total paid, and payoff date
- Assumes extra payment applied same day as regular payment
6. Mortgage Affordability
28/36 Rule Implementation
Front-end limit = Gross Monthly Income × 0.28 Back-end limit = Gross Monthly Income × 0.36 - Monthly Debts Max Monthly Payment = min(Front-end limit, Back-end limit) Max Loan = PV(Max Monthly Payment - Tax - Insurance - PMI, rate, term) Max Home Price = Max Loan / (1 - Down Payment %)
Assumptions
- Property tax: 1.2% of home value annually (configurable per country)
- Insurance: 0.35% of home value annually
- PMI: 0.75% of loan annually if down payment < 20%
Sources
- CFPB "Ability-to-Repay" rule (12 CFR 1026.43)
- Fannie Mae/Freddie Mac underwriting guidelines
- UK FCA MCOB affordability assessment
7. Savings Goal
Formula
PMT = (FV - PV(1+r)^n) / [((1+r)^n - 1)/r] Where: FV = Target amount PV = Current savings r = Monthly rate n = Months to target date
If target date is in the past or current savings ≥ target, shows shortfall/surplus.
8. Debt Payoff Planner
Avalanche Method
- Sort debts by interest rate descending
- Pay minimums on all
- Apply extra to highest rate debt
- When paid, roll payment to next highest rate
Snowball Method
- Sort debts by balance ascending
- Same process, targeting smallest balance first
Comparison
Also calculates "minimum payments only" baseline for savings comparison.
9. Retirement Savings
Accumulation Phase
FV = PV(1+r)^n + PMT × [((1+r)^n - 1)/r]
Withdrawal Phase
- Fixed annual withdrawal (inflation-adjusted each year)
- Portfolio earns returns on remaining balance
- Stops when balance ≤ 0 or max years reached
- Sustainable withdrawal = Portfolio × 4% (configurable)
Real Values
RealBalance = NominalBalance / (1 + inflation)^years
10. Net Worth
Formula
Net Worth = Σ Assets - Σ Liabilities Liquid Net Worth = (Cash + Investments) - Σ Liabilities Debt-to-Asset Ratio = Total Liabilities / Total Assets
Categories are for organization only; all assets/liabilities weighted equally.
11. Budget Calculator
Frequency Normalization
Monthly Equivalent = Amount × Frequency Multiplier Multipliers: Monthly = 1 Biweekly = 26/12 ≈ 2.1667 Weekly = 52/12 ≈ 4.3333 Annually = 1/12 ≈ 0.0833
50/30/20 Analysis
Needs Budget = Gross Income × 0.50 Wants Budget = Gross Income × 0.30 Savings Budget = Gross Income × 0.20 Category Mapping: Needs: Housing, Transportation, Food, Utilities, Insurance, Healthcare, Debt Wants: Entertainment, Personal Savings: Savings, Investments
12. Wealth Simulator (Monte Carlo)
Algorithm
- For each simulation (default 100):
- For each year: Annual Return ~ N(μ, σ) where μ = expected return, σ = volatility
- Balance = Previous × (1 + Return) + Annual Contribution
- Track balance at each year
- After all simulations: Calculate percentiles (P10, P25, P50, P75, P90) per year
Limitations
- Assumes normal distribution (markets have fat tails)
- No mean reversion
- No correlation between asset classes (single portfolio)
- Constant volatility assumption
- 100 simulations for speed; 10,000+ recommended for production
Sources
- Hull, "Options, Futures, and Other Derivatives" Ch. 14
- Kitces, "Monte Carlo Analysis for Financial Planning"
- Vanguard Capital Markets Model methodology
Testing & Validation
- Unit tests: 100+ test cases covering edge cases, known values, boundary conditions
- Cross-reference: Results compared to Excel, financial calculators (HP 12C, TI BA II+)
- Regression: Automated tests on every commit
- Precision: Verified to within $0.01 for currency, 0.0001 for rates