budget-app/README.md

BudgetWise

A personal budgeting PWA with self-hosted Appwrite 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

git clone <repo>
cd budget
npm install

2. Configure environment

cp .env.example .env

Edit .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):

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

npm run setup:appwrite

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

5. Build & deploy

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

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