# Return Calculator Logic & Implementation Guide

This guide provides the mathematical formulas, step-by-step logic, and code examples for implementing a **Return Calculator** for both **One-Time (Lump Sum)** and **Monthly SIP** investments, based on an annual compound growth rate (CAGR).

---

## 1. Concepts & Variables

* **`P`**: Principal amount for a One-Time investment (e.g., ৳ 50,000)
* **`D`**: Monthly deposit amount for SIP (e.g., ৳ 5,000)
* **`CAGR` / `r`**: Annualized growth rate as a decimal (e.g., $11.47\% \rightarrow 0.1147$)
* **`t`**: Duration in years (e.g., 1, 3, 5, 10, 15)
* **`n`**: Total number of months ($n = t \times 12$)
* **`i`**: Equivalent monthly growth rate derived from annual CAGR

---

## 2. Calculation Logic

### A. One-Time (Lump Sum) Investment

#### Formulas

1. **Future Value ($M$):**
   $$M = P \times (1 + r)^t$$

2. **Total Investment ($I$):**
   $$I = P$$

3. **Returns Percentage ($R$):**
   $$R = \left( \frac{M - I}{I} \right) \times 100$$

---

### B. Monthly SIP Investment

#### Formulas

1. **Monthly Equivalent Growth Rate ($i$):**
   $$i = (1 + r)^{\frac{1}{12}} - 1$$
   *(Uses the 12th root for accurate compounding across monthly intervals).*

2. **Future Value ($M$) — Annuity Due (Deposits at the start of each month):**
   $$M = D \times \frac{(1 + i)^n - 1}{i} \times (1 + i)$$

3. **Total Investment ($I$):**
   $$I = D \times n$$

4. **Returns Percentage ($R$):**
   $$R = \left( \frac{M - I}{I} \right) \times 100$$

---

## 3. Worked Examples ($CAGR = 11.47\%$, Duration = 1 Year)

### Example 1: One-Time Investment (৳ 50,000)
* $P = 50,000$
* $r = 0.1147$
* $t = 1$

1. **Future Value ($M$):**
   $$M = 50,000 \times (1 + 0.1147)^1 = 55,735$$
2. **Total Investment ($I$):**
   $$I = 50,000$$
3. **Returns Percentage ($R$):**
   $$R = \left( \frac{55,735 - 50,000}{50,000} \right) \times 100 = 11.47\%$$

---

### Example 2: Monthly SIP Investment (৳ 5,000 / month)
* $D = 5,000$
* $r = 0.1147$
* $t = 1 \implies n = 12$

1. **Monthly Rate ($i$):**
   $$i = (1 + 0.1147)^{\frac{1}{12}} - 1 \approx 0.00910403 \text{ (0.9104\%/month)}$$

2. **Future Value ($M$):**
   $$M = 5,000 \times \frac{(1 + 0.00910403)^{12} - 1}{0.00910403} \times (1 + 0.00910403)$$
   $$M = 5,000 \times 12.59864 \times 1.00910403 \approx 63,566$$

3. **Total Investment ($I$):**
   $$I = 5,000 \times 12 = 60,000$$

4. **Returns Percentage ($R$):**
   $$R = \left( \frac{63,566 - 60,000}{60,000} \right) \times 100 \approx 5.94\%$$

---

## 4. Reference Code Implementation (TypeScript / JavaScript)

```typescript
interface ReturnProjection {
  years: number;
  totalInvestment: number;
  wouldHaveBecome: number;
  returnsPercentage: number;
}

/**
 * Calculates Lump Sum (One-Time) Return Projections
 */
export function calculateLumpSum(
  principal: number,
  cagrPercentage: number,
  yearsList: number[] = [1, 3, 5, 10, 15]
): ReturnProjection[] {
  const r = cagrPercentage / 100;

  return yearsList.map((years) => {
    const totalInvestment = principal;
    const wouldHaveBecome = Math.round(principal * Math.pow(1 + r, years));
    const returnsPercentage = Number(
      (((wouldHaveBecome - totalInvestment) / totalInvestment) * 100).toFixed(2)
    );

    return {
      years,
      totalInvestment,
      wouldHaveBecome,
      returnsPercentage,
    };
  });
}

/**
 * Calculates Monthly SIP Return Projections
 */
export function calculateSIP(
  monthlyAmount: number,
  cagrPercentage: number,
  yearsList: number[] = [1, 3, 5, 10, 15]
): ReturnProjection[] {
  const r = cagrPercentage / 100;
  // Convert annual rate to equivalent monthly rate
  const i = Math.pow(1 + r, 1 / 12) - 1;

  return yearsList.map((years) => {
    const n = years * 12;
    const totalInvestment = monthlyAmount * n;

    // Annuity Due formula
    const wouldHaveBecome = Math.round(
      monthlyAmount * (((Math.pow(1 + i, n) - 1) / i) * (1 + i))
    );

    const returnsPercentage = Number(
      (((wouldHaveBecome - totalInvestment) / totalInvestment) * 100).toFixed(2)
    );

    return {
      years,
      totalInvestment,
      wouldHaveBecome,
      returnsPercentage,
    };
  });
}
```

---

## 5. Summary Rules for Cursor Agent
* Always convert CAGR percentages to decimal format ($11.47\% \rightarrow 0.1147$) before running compounding logic.
* Always use monthly rate conversion via compounding power $(1+r)^{1/12}-1$ rather than simple division $r/12$.
* SIP deposits occur at the **beginning** of the month, requiring the multiplication by $(1 + i)$ in the annuity calculation.