feat: initial BudgetWise budgeting app with Appwrite sync
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
This commit is contained in:
Claude
129
README.md
Normal file
129
README.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user