BudgetBox - Offline-First Personal Budgeting App

Anshumat Foundation Selection Assignment

"Educate. Employ. Empower." - Building resilient software for the #DigitalForAll initiative

---

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Python 3.10+
• PostgreSQL (optional for production)

Backend Setup

cd backend
python -m venv venv

# Windows
.\venv\Scripts\Activate.ps1

# Linux/Mac
source venv/bin/activate

pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Backend will run on: http://localhost:8000
API Docs: http://localhost:8000/docs

Frontend Setup

cd frontend
npm install
npm run dev

Frontend will run on: http://localhost:3000

---

📸 Screenshots

Login Page

Dashboard with Budget Data

Initial Load (Empty State)

With Budget Data & Anomaly Warnings

---

✨ Features

Offline-First Architecture

• ✅ IndexedDB Storage - All data saved locally via LocalForage
• ✅ Auto-Save - Every keystroke persists immediately
• ✅ Sync Engine - Background sync when network returns
• ✅ 3-State Sync - Local Only | Sync Pending | Synced

Budget Management

• ✅ 6 Budget Categories - Income, Bills, Food, Transport, Subscriptions, Misc
• ✅ Real-Time Dashboard - Burn Rate, Savings, Month-End Prediction
• ✅ Pie Chart Visualization - Category breakdown using Recharts

Rule-Based Anomaly Detection (No AI)

• ⚠️ Food > 40% of income → Warning
• ⚠️ Subscriptions > 30% of income → Warning
• ⚠️ Negative savings → Critical alert

Accessibility

• ✅ WCAG Compliant - ARIA labels on all inputs
• ✅ Keyboard Navigation - Full keyboard support
• ✅ Low Bandwidth - Optimized for 2G/3G networks

No AI Dependency

• ✅ Rule-Based Logic - All anomaly detection uses hardcoded thresholds
• ✅ No LLM APIs - Zero dependency on ChatGPT/OpenAI or similar services
• ✅ Pure TypeScript/Python - Handwritten business logic
• ✅ Transparent Calculations - All metrics computed with simple math

---

📁 Project Structure

/anshu_budget_1/
├── docs/                       # Documentation
│   ├── Assignment A – BudgetBox.txt
│   ├── plan.txt
│   ├── project_structure.md
│   └── best_practices.md
├── frontend/                   # Next.js 15 App
│   ├── app/
│   │   └── page.tsx           # Main application
│   ├── components/
│   │   ├── forms/BudgetForm.tsx
│   │   ├── dashboard/Dashboard.tsx
│   │   └── sync/OfflineIndicator.tsx
│   ├── lib/
│   │   ├── store/useBudgetStore.ts
│   │   ├── sync/useSyncManager.ts
│   │   └── utils/anomalyDetection.ts
│   └── package.json
└── backend/                    # FastAPI
    ├── app/
    │   ├── main.py
    │   ├── api/v1/endpoints/budget.py
    │   └── schemas/budget.py
    └── requirements.txt

---

🔑 Demo Credentials

Email: hire-me@anshumat.org
Password: HireMe@2025!

---

🧪 Testing Offline Mode

1. Open http://localhost:3000
2. Enter budget data (all fields auto-save)
3. Open DevTools → Network → Set to "Offline"
4. Refresh the page
5. ✅ Data persists! Status shows "Offline"
6. Go back online
7. Click "Sync Now" → Status changes to "Synced"

---

📊 Tech Stack

Frontend:

• Next.js 15 (App Router)
• React 18 + TypeScript
• TailwindCSS
• Zustand (state management)
• LocalForage (IndexedDB)
• Recharts (charts)

Backend:

• FastAPI 0.115.6
• Pydantic (validation)
• SQLAlchemy + PostgreSQL
• Uvicorn (ASGI server)

---

🌐 Deployment

Frontend (Vercel)

cd frontend
vercel --prod

Backend (Railway/Render)

cd backend
# Deploy via Railway CLI or Render dashboard

---

📝 Assignment Compliance

Requirement	Status
Offline-First	✅ IndexedDB + Auto-save
Budget Form	✅ 6 fields with auto-save
Dashboard	✅ Metrics + Pie Chart
Anomaly Alerts	✅ Rule-based (no AI)
Sync Logic	✅ 3-state sync
Next.js 15	✅ App Router
FastAPI	✅ /sync + /latest endpoints
Demo Credentials	✅ Hardcoded
Accessibility	✅ ARIA labels

---

📞 Contact

Built for: Anshumat Foundation
Mission: Educate. Employ. Empower.
Initiative: #DigitalForAll

CIN: U88900WB2024NPL275378
Website: http://anshumat.org