# Rural Livelihood Transition Simulator

An En-ROADS-style interactive policy simulator for the Nepal/Myanmar/Bhutan rural livelihood transition model. Built on MIT System Dynamics Group principles.

## Quick Start (Local)

**Step 1 — Backend**
```bash
cd backend/
pip install -r requirements.txt

# Copy or symlink my.mdl into backend/
cp /path/to/my.mdl ./my.mdl

python main.py   # FastAPI at http://localhost:8000
```

**Step 2 — Frontend** (separate terminal)
```bash
cd frontend/
npm install
npm run dev      # Vite at http://localhost:5173
```

Open **http://localhost:5173** in your browser. Sliders update charts instantly.

## Project Structure

```
simulator/
├── backend/
│   ├── main.py          # FastAPI app (API + serves built frontend)
│   ├── model_runner.py  # PySD model wrapper
│   ├── my.mdl           # Vensim model file (symlink or copy)
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── App.tsx               # Root layout
│   │   ├── components/           # Slider, Chart, KPICard, ScenarioButtons
│   │   ├── hooks/                # useSimulation, useUrlState
│   │   ├── config/               # sliders.ts, countries.ts, scenarios.ts, charts.ts
│   │   └── styles/               # tokens.css, global.css, slider.css, kpi.css, chart.css
│   └── dist/                     # Built output (after npm run build)
└── render.yaml                   # Render.com deployment config
```

## Production Build

```bash
cd frontend && npm run build      # builds to frontend/dist/
cd ../backend && python main.py   # FastAPI serves API + built React from /
```

Visit **http://localhost:8000** — single process, single URL.

## Deploy to Render.com (Free)

1. Push this `simulator/` folder to a GitHub repo
2. Add `my.mdl` to `backend/` (do not commit sensitive data)
3. Connect repo at [render.com](https://render.com) → New Web Service → use `render.yaml`
4. Build runs automatically; your app is live at `https://your-app.onrender.com`

## Features

| Feature | Details |
|---------|---------|
| **5 policy sliders** | Climate shock frequency & severity, education coverage, income support, infrastructure investment |
| **4 Plotly charts** | Livelihood transition, household income, resilience, climate damage |
| **3 KPI cards** | % in new livelihoods, income growth vs baseline, resilience index |
| **Grey baseline** | BAU dashed reference always visible |
| **4 scenario buttons** | BAU, Edu+, Infra+, Best Case |
| **Shareable URLs** | All slider values encoded in URL params |
| **Country toggle** | Nepal / Myanmar / Bhutan (different base incomes) |
| **Slider info panels** | Click any slider label → expand with description + citation |
| **Chart info panels** | ℹ button → plain-language interpretation |
| **Mobile-friendly** | Touch sliders, responsive layout |

## Technology

- **Backend**: FastAPI + PySD (reads `.mdl` directly → pandas DataFrame → JSON)
- **Frontend**: React + Vite + TypeScript + Plotly.js
- **Design**: Custom CSS, Inter font (same as En-ROADS), En-ROADS-matching color palette
- **Architecture**: Same frontend/model split as En-ROADS (Climate Interactive)

