37bc35f53f
Full-stack PWA budgeting app installable on Android via Chrome. Features implemented: - Monthly balance sheet: income sources (monthly/yearly), buffer (fixed $ or % of income) - Buckets: regular, savings-goal, and investment types with custom goals (amount or % of income, monthly or yearly schedule) - Debt tracker: manual or auto-EMI (amortization formula), interest rate, remaining balance tracking, avalanche-method repayment suggestions - Loan calculator: max affordable principal and EMI checker based on remaining income after all expenses - Investment projections: compound interest at monthly/yearly rate, 1/5/10-year projections per bucket - Deposit / withdraw transactions per bucket with balance history - Appwrite self-hosted backend: auth, 5 collections (balance_sheets, incomes, buckets, debts, transactions) - scripts/setup-appwrite.cjs: one-command DB setup via node-appwrite - PWA manifest + service worker (vite-plugin-pwa) for Android install - Dark mobile-first UI with TailwindCSS, Zustand state, React Router v6 https://claude.ai/code/session_01Ny2EMaZYvzk5SSVDAPgxpP
130 lines
3.6 KiB
Markdown
130 lines
3.6 KiB
Markdown
# 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
|
||
```
|