# Personal Financial Planning Scenario Planner

A free, single-page web app for exploring a **simplified** personal financial
plan: how your savings might grow toward retirement, whether you're roughly
"on track," and how a major future expense (like education, a home, or
travel) might affect that picture.

This project was built as a **workshop demonstration** of how an AI coding
agent can turn a plain-language idea into a working, publicly hosted website.

> ⚠️ **This is an educational tool, not financial advice.** It uses
> simplified assumptions and cannot predict real markets, taxes, or your
> personal situation. Always consult a qualified professional before making
> financial decisions.

---

## What the app does

Open the page and you'll see a form with your basic financial details
(age, income, savings, expenses, etc.) and three preset **scenarios**
(Conservative, Moderate, Optimistic) that set assumptions like investment
return, income growth, and inflation. You can also fine-tune any assumption
yourself.

As you type, the app instantly recalculates and shows:

- Estimated savings at retirement
- Estimated savings after your optional major expense
- Estimated first-year retirement spending (adjusted for inflation)
- Whether the plan looks "on track" (using a simplified 4% withdrawal rule)
- The estimated dollar gap or surplus
- A year-by-year projection chart of your savings balance
- A side-by-side comparison of all three scenarios

Everything runs **entirely in your browser**. No data is ever sent to a
server, saved to a file, or stored in a cookie/localStorage — refresh the
page and it's gone. That also means it's free to host and has no login,
database, or API key to manage.

---

## Project file structure

```
.
├── index.html          # Page structure: form, results, charts
├── css/
│   └── styles.css      # All styling (responsive, accessible, print-friendly)
├── js/
│   └── app.js          # All calculation logic + chart drawing + interactivity
├── README.md            # This file
├── LICENSE               # MIT open-source license
└── .gitignore            # Files Git should ignore
```

There is no build step, no package manager, and no server-side code —
just three files your browser reads directly.

---

## How to preview it locally

Because the app is plain HTML/CSS/JS, you have two easy options:

**Option A — just double-click it**
Open `index.html` directly in your web browser (Chrome, Firefox, Edge,
Safari). Everything will work since the app makes no external requests.

**Option B — use a tiny local server (optional, closer to production)**
Some browsers are stricter about files opened directly from disk. If
anything looks off, run a simple local server from this folder:

```bash
# Python (usually pre-installed on Mac/Linux)
python3 -m http.server 8000
```

Then visit `http://localhost:8000` in your browser.

---

## How to publish it for free with GitHub Pages

You don't need any technical background for this — just follow the steps
in order.

### 1. Create a GitHub account (if you don't have one)
Go to [github.com](https://github.com) and sign up for a free account.

### 2. Create a new repository
1. Click the **+** icon (top right of GitHub) → **New repository**.
2. Give it a name, e.g. `financial-planning-scenario-planner`.
3. Set it to **Public** (required for free GitHub Pages).
4. Do **not** check "Add a README" — you already have one.
5. Click **Create repository**.

### 3. Upload or push the files

**Easiest option (no command line): drag-and-drop**
1. On your new repository's page, click **uploading an existing file**.
2. Drag in all the project files and folders (`index.html`, `css/`, `js/`,
   `README.md`, `LICENSE`, `.gitignore`).
3. Scroll down and click **Commit changes**.

**Command-line option (if you're comfortable with git)**
```bash
cd path/to/this/project
git init
git add .
git commit -m "Initial commit: Personal Financial Planning Scenario Planner"
git branch -M main
git remote add origin https://github.com/YOUR-USERNAME/YOUR-REPO-NAME.git
git push -u origin main
```

### 4. Enable GitHub Pages
1. In your repository, go to **Settings** (top menu).
2. In the left sidebar, click **Pages**.
3. Under **Build and deployment → Source**, choose **Deploy from a branch**.
4. Under **Branch**, choose `main` and folder `/ (root)`, then click **Save**.
5. Wait a minute or two — GitHub will build and publish your site.

### 5. Find your public website URL
Refresh the **Settings → Pages** screen. GitHub will show a message like:

> Your site is live at `https://YOUR-USERNAME.github.io/YOUR-REPO-NAME/`

That's your public link! Share it with anyone — no installation needed.

---

## How to make future changes using Codex (or Claude Code)

You can keep improving the site using an AI coding agent (such as Codex or
Claude Code) even without writing code yourself:

1. Open the project folder with the AI coding agent (in your terminal or
   editor extension).
2. Describe the change you want in plain English, e.g.:
   - *"Add a field for expected Social Security income."*
   - *"Change the color scheme to blue."*
   - *"Add a fourth scenario called 'Custom'."*
3. Review the changes the agent makes (it will show you a diff of what
   changed).
4. Test locally by opening `index.html` again (see "How to preview it
   locally" above).
5. When you're happy with the result, commit and push the changes:
   ```bash
   git add .
   git commit -m "Describe what changed"
   git push
   ```
6. GitHub Pages will automatically redeploy your site within a minute or
   two — refresh your public URL to see the update.

---

## Limitations and assumptions in the calculations

This tool intentionally uses a **simplified** model so the math stays
transparent and explainable. Key assumptions:

- **Constant average returns.** Investment growth is applied as a flat
  average rate every month. Real markets go up and down unpredictably —
  this model does not simulate market crashes, volatility, or sequence-of-
  returns risk.
- **Contribution growth.** Your monthly savings contribution is assumed to
  grow once a year at the same rate as your "income growth" assumption
  (the idea being that people tend to save a steady share of a growing
  income). It does not model raises, bonuses, or career changes directly.
- **Retirement withdrawals.** In retirement, the model withdraws your
  target spending amount each year (adjusted for inflation) and continues
  applying the same average investment return to the remaining balance.
  It does not adjust the investment mix or return rate after retirement.
- **"On track" rule.** The plan is judged "on track" using the widely
  cited but simplified **4% rule**: if 4% of your projected savings at
  retirement would cover your first-year retirement spending, the plan is
  marked on track. Real safe withdrawal rates vary with market conditions,
  taxes, life expectancy, and other factors not modeled here.
- **No taxes.** The model does not account for income tax, capital gains
  tax, tax-advantaged accounts (401k/IRA equivalents), or Social
  Security/pension income.
- **Single major expense.** Only one optional lump-sum future expense is
  supported, applied in full (inflation-adjusted) in the year you specify.
- **Rounding and horizon.** Projections run to at least age 95 (or a few
  years past retirement, whichever is later) and are capped at age 100.

Because of these simplifications, treat every number the app shows as a
**rough, illustrative estimate** — useful for understanding how the pieces
of a financial plan interact, not as a prediction of your actual future.

---

## License

Released under the [MIT License](LICENSE) — free to use, modify, and share.