# BudgetWise

A personal budgeting PWA with self-hosted [Appwrite](https://appwrite.io) sync — installable as an Android app.

## Features

| Feature | Details |
|---|---|
| **Monthly balance sheet** | Track income sources (monthly or yearly), set a monthly buffer (fixed amount or % of income) |
| **Buckets** | Regular, savings-goal, and investment buckets with custom goals (amount or % of income, monthly or yearly) |
| **Investment returns** | Track projected returns at a monthly or annual rate, see 1/5/10-year projections |
| **Debt tracker** | Manual or auto-EMI calculation, interest rate (monthly/yearly), amortization tracking |
| **Auto repayment plan** | After all expenses, avalanche-method suggestion for extra debt repayment |
| **Loan calculator** | Max affordable loan based on remaining income after buffer + buckets + debts |
| **Deposit / Withdraw** | Manual transactions per bucket, balance history |
| **PWA / Android** | Installable via Chrome "Add to Home Screen" |
| **Offline capable** | Service worker caches the app shell |

---

## Tech Stack

- **React 18** + **TypeScript** + **Vite**
- **TailwindCSS** (dark theme, mobile-first)
- **Appwrite JS SDK** (self-hosted database & auth)
- **Zustand** (state management)
- **vite-plugin-pwa** (service worker + web manifest)

---

## Setup

### 1. Clone & install

```bash
git clone <repo>
cd budget
npm install
```

### 2. Configure environment

```bash
cp .env.example .env
```

Edit `.env`:

```env
VITE_APPWRITE_ENDPOINT=https://your-appwrite.example.com/v1
VITE_APPWRITE_PROJECT_ID=your-project-id
APPWRITE_API_KEY=your-server-api-key    # only for setup script
```

### 3. Set up Appwrite

Install Appwrite (Docker):

```bash
docker run -it --rm \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \
  --entrypoint="install" \
  appwrite/appwrite:latest
```

Then:

1. Open your Appwrite console → **Create Project** → note the **Project ID**
2. Go to **API Keys** → create a key with `databases.write` permission
3. Add the key to `.env` as `APPWRITE_API_KEY`

### 4. Create database collections

```bash
npm run setup:appwrite
```

This creates the `budget_db` database with all five collections and their attributes/indexes.

### 5. Build & deploy

```bash
npm run build
# Deploy dist/ to any static host (Nginx, Caddy, Netlify, Vercel…)
```

> **HTTPS is required** for the PWA install prompt and service worker.

### 6. Install on Android

1. Open the app URL in **Chrome on Android**
2. Tap the **three-dot menu** → **Add to Home Screen**
3. The app now runs as a standalone PWA with its own icon and no browser chrome

---

## Data Model

```
balance_sheets   month, year, buffer_type, buffer_value
incomes          balance_sheet_id, name, amount, frequency
buckets          name, type, current_balance, goal_*, return_*, color
debts            name, principal, remaining_balance, interest_rate, term_months, monthly_payment
transactions     bucket_id, type, amount, date, notes, balance_after
```

---

## Key calculations

| Formula | Where used |
|---|---|
| Monthly income | Sum of incomes (yearly ones ÷ 12) |
| Buffer | Fixed $ or % × monthly income |
| Bucket allocation | Goal amount or % of income, divided by 12 for yearly goals |
| EMI | `P × r × (1+r)^n / ((1+r)^n − 1)` |
| Max loan | `payment × (1 − (1+r)^−n) / r` |
| Investment projection | Compound interest `P × (1+r)^n` |

---

## Development

```bash
npm run dev       # Start dev server at http://localhost:5173
npm run build     # Production build
npm run preview   # Preview production build locally
```