Scenario Explorer & Loan Calculator

POST /api/v1/loan-calculator/calculate
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "principal": 150000,
  "term_months": 36,
  "annual_interest_rate": 0.045,
  "application_id": "app_20251222_143023_usr123"
}

{
  "request_id": "req_cm06_20251222_143715",
  "status": "success",
  "calculation": {
    "monthly_payment": 4440,
    "total_interest": 9840,
    "total_repayment": 159840,
    "apr": 0.045
  },
  "affordability": {
    "disposable_income_monthly": 6240,
    "payment_to_income_ratio": 0.711,
    "cashflow_buffer": 1800,
    "status": "comfortable",  // "comfortable", "manageable", "tight"
    "recommendation": "This leaves you a healthy operational cushion"
  },
  "amortization_schedule": [
    {
      "month": 1,
      "payment": 4440,
      "principal": 3877,
      "interest": 563,
      "balance": 146123
    },
    // ... 35 more months
  ],
  "processing_time_ms": 12,
  "timestamp": "2025-12-22T14:37:15Z"
}

POST /api/v1/applications/app_20251222_143023_usr123/save-scenario

{
  "chosen_amount": 150000,
  "chosen_term_months": 36,
  "monthly_payment": 4440,
  "total_interest": 9840,
  "scenarios_explored": 7,  // Number of slider adjustments
  "time_spent_seconds": 145
}

// Calculate monthly payment using PMT formula

function calculateMonthlyPayment(principal, annualRate, months) {
  // Convert annual rate to monthly
  const monthlyRate = annualRate / 12;
  
  // Handle edge case: 0% interest
  if (monthlyRate === 0) {
    return principal / months;
  }
  
  // PMT formula: P × [r(1+r)^n] / [(1+r)^n - 1]
  const x = Math.pow(1 + monthlyRate, months);
  const monthly = principal * (monthlyRate * x) / (x - 1);
  
  return Math.round(monthly); // Round to nearest pound
}

// Calculate total interest
function calculateTotalInterest(monthlyPayment, months, principal) {
  const totalRepayment = monthlyPayment * months;
  return totalRepayment - principal;
}

// Assess affordability
function assessAffordability(monthlyPayment, disposableIncome) {
  const ratio = monthlyPayment / disposableIncome;
  const buffer = disposableIncome - monthlyPayment;
  
  let status, message;
  
  if (ratio < 0.60 && buffer > 2000) {
    status = 'comfortable';
    message = 'This leaves you a healthy operational cushion';
  } else if (ratio < 0.75 && buffer > 500) {
    status = 'manageable';
    message = 'This is manageable. Consider extending term if needed.';
  } else {
    status = 'tight';
    message = 'This would be challenging. We recommend reducing amount or extending term.';
  }
  
  return { status, ratio, buffer, message };
}

// Real-time update on slider change
function updateCalculations() {
  const principal = parseInt(amountSlider.value);
  const years = parseInt(termSlider.value);
  const months = years * 12;
  const rate = 0.045; // From CM05 credit assessment
  
  const monthlyPayment = calculateMonthlyPayment(principal, rate, months);
  const totalInterest = calculateTotalInterest(monthlyPayment, months, principal);
  const affordability = assessAffordability(monthlyPayment, 6240);
  
  // Update UI instantly
  updateUI(monthlyPayment, totalInterest, affordability);
}

function generateAmortizationSchedule(principal, annualRate, months) {
  const monthlyRate = annualRate / 12;
  const monthlyPayment = calculateMonthlyPayment(principal, annualRate, months);
  
  const schedule = [];
  let balance = principal;
  
  for (let month = 1; month <= months; month++) {
    const interest = Math.round(balance * monthlyRate);
    const principalPayment = monthlyPayment - interest;
    balance -= principalPayment;
    
    schedule.push({
      month,
      payment: monthlyPayment,
      principal: principalPayment,
      interest,
      balance: Math.max(0, balance) // Avoid negative due to rounding
    });
  }
  
  return schedule;
}