💰 SmartBudget — Personal Finance Manager

v1.0 . Built for the Product Management Hackathon

A modern, fully client-side budgeting web app built with pure HTML, CSS, and JavaScript. No backend. No installation. No account required to get started.

---

📋 Table of Contents

• Quick Start
• Features
• Authentication System
• Project Structure
• Tech Stack
• Pages & Sections
• Transaction Categories
• localStorage Schema
• Browser Support
• Development Notes
• Roadmap

---

🚀 Quick Start

Fastest Way

Just open index.html in any modern browser — done.

No npm, no build step, no server required.

Optional — Local Server

# Python
python3 -m http.server 8080

# Node.js
npx serve .

# VS Code
# Install the "Live Server" extension → click Go Live

Then open: http://localhost:8080

---

✨ Features

🔐 Authentication

• Register a new account with name, email, and password
• Sign In with your registered credentials
• Guest mode — jump straight in with no account needed
• Sign Out button in both the Topbar and Sidebar
• Session persists across browser refreshes via localStorage
• Passwords are encoded before storage
• Password strength meter shown during registration
• Show / hide password toggle on all password fields

💳 Transactions — Full CRUD

Operation	Description
➕ Create	Add income or expense via modal form
📋 Read	View all transactions in a paginated, filterable table
✏️ Update	Edit any transaction inline — opens pre-filled modal
🗑️ Delete	Remove a transaction with a confirmation prompt

Filter options: keyword search · type (income / expense) · category · month

📊 Dashboard

• Summary cards — Total Income, Total Expenses, Net Balance, Transaction Count
• Current month stats on each card
• Monthly bar chart — Income vs Expenses (last 6 months)
• Doughnut chart — Spending breakdown by category
• Recent Transactions table (last 5 entries)

📈 Analytics

• Bar chart — Monthly income vs expenses comparison
• Doughnut chart — Category spending distribution
• Line chart — Net balance trend over 6 months
• Category summary list with animated progress bars and percentages

🎯 Budget Goals

• Set a monthly spending limit per category
• Visual progress bar showing % of budget used
• Automatic over-budget alert (turns red when exceeded)
• Full CRUD — add, edit, and delete budget goals

🎨 UI / UX

• Dark / Light Mode toggle — saved across sessions
• Fully responsive — mobile, tablet, and desktop layouts
• Smooth page transitions and hover animations
• Toast notifications for every user action
• Collapsible sidebar drawer on mobile

💾 Data Management

• Auto-save to localStorage on every change
• Export CSV — open in Excel or Google Sheets
• Export JSON — full backup of all data
• Import JSON — restore from a backup file
• Clear All Data option in Settings

---

🔐 Authentication System

The app uses a fully client-side authentication system — no server or API involved.

Flow

User opens the app
        ↓
Is there a saved session?
   ↓ Yes                  ↓ No
Load app directly    Show Login / Register screen

localStorage Keys Used by Auth

Key	Contents
sb_users	Array of all registered user accounts
sb_sess	Current active session object
sb_data	Transactions, budgets, and settings

Password Storage

Passwords are encoded with btoa() before being stored in localStorage. This is suitable for a prototype / hackathon build. For production, replace with server-side hashing (e.g. bcrypt).

User Entry Points

New user      →  Register tab  →  Auto sign-in after success
Existing user →  Sign In tab   →  Direct access
No account    →  Guest button  →  Temporary session

---

📁 Project Structure

smartbudget/
│
├──assets/logo.png
├── index.html  
├── README.md    
├── script.js     
└── style.css

Note: The entire app lives in a single index.html file. CSS is inside <style> tags. JavaScript is inside <script> tags. This makes it fully portable — email it, put it on a USB drive, or host it for free.

---

🛠️ Tech Stack

Layer	Technology
Markup	HTML5
Styling	CSS3 — Custom Properties, Grid, Flexbox, Keyframe Animations
Logic	Vanilla JavaScript (ES6+)
Charts	Chart.js v4 (loaded via CDN)
Fonts	Google Fonts — Syne (headings) + DM Sans (body)
Persistence	Browser localStorage API
Authentication	Client-side localStorage (no backend)
Build Tool	❌ None
Backend	❌ None
External Dependencies	Chart.js only

---

📱 Pages & Sections

Page	What's Inside
🔐 Auth Screen	Sign In form · Create Account form · Guest access
📊 Dashboard	Stat cards · Monthly chart · Category chart · Recent transactions
💳 Transactions	Full table · Filters · Pagination · Add / Edit / Delete
📈 Analytics	Bar chart · Doughnut chart · Trend line · Category breakdown
🎯 Budgets	Budget goal cards · Progress bars · Over-budget alerts
⚙️ Settings	Theme toggle · Currency selector · Export / Import / Clear data

---

🏷️ Transaction Categories

Expense Categories

Icon	Category
🍽️	Food & Dining
🚗	Transport
🏠	Housing
💊	Health
🎬	Entertainment
🛍️	Shopping
📚	Education
⚡	Utilities
📦	Other

Income Categories

Icon	Category
💼	Salary
💻	Freelance
📈	Investment
🎁	Gift
💰	Other

---

💾 localStorage Schema

// Key: sb_data
{
  "tx": [
    {
      "id": "lrk2abc9x",
      "type": "expense",
      "desc": "Grocery Shopping",
      "amount": 180.00,
      "date": "2025-01-15",
      "cat": "food",
      "note": "Weekly groceries"
    }
  ],
  "budgets": [
    {
      "id": "mzt4def2y",
      "cat": "food",
      "limit": 400
    }
  ],
  "settings": {
    "currency": "$",
    "dark": true
  }
}

// Key: sb_users
[
  {
    "id": "uid123",
    "firstName": "Ahmed",
    "lastName": "Hassan",
    "email": "ahmed@example.com",
    "pw": "encoded_password"
  }
]

// Key: sb_sess
{
  "id": "uid123",
  "firstName": "Ahmed",
  "lastName": "Hassan",
  "email": "ahmed@example.com"
}

---

🌐 Browser Support

Browser	Minimum Version
Chrome	90+
Firefox	88+
Safari	14+
Edge	90+
Opera	76+

Requires: CSS Custom Properties, ES6+, localStorage, Fetch API (Chart.js CDN)

---

🏗️ Development Notes

• ~1,200 lines of code (excluding blank lines and comments)
• Single-file architecture — entire app in one portable index.html
• Demo data is seeded automatically on first login if no transactions exist
• Chart.js instances are destroyed and re-created on theme toggle to prevent canvas conflicts
• All currency values formatted with the user's selected currency symbol
• The renderAll() function is the single source of truth — called after every data mutation
• Sidebar navigation uses a data attribute data-p for section routing
• Modal forms are reused for both Add and Edit modes via S.editTx state flag

---

🔮 Roadmap

Phase 2 — Near Term

• Recurring / scheduled transactions
• Multiple wallets or accounts
• PDF monthly report export
• PWA support — installable on mobile

Phase 3 — Growth

• Optional cloud sync (Firebase or Supabase)
• Multi-currency with live conversion rates
• AI-powered spending insights
• Receipt photo upload and OCR

Phase 4 — Monetization

• Pro tier with advanced analytics
• Family / team shared budgets
• White-label licensing for financial apps
• Affiliate integrations with financial products

---

📄 License

This project was created during a Product Management Hackathon. Free to use, modify, and distribute for personal and educational purposes.

---

SmartBudget — Budget smarter. Live better.

Built with ❤️ using pure HTML, CSS & JavaScript