Budget App

A powerful, privacy-focused budget projection tool that runs entirely in your browser. No accounts, no servers, no subscriptions—just you and your finances.

Screenshots

---

Table of Contents

• Why Budget App?
• Features
• Quick Start
• User Guide
• Data Management
• Technical Details
• Contributing
• Roadmap
• FAQ
• License
• Contact

---

Why Budget App?

Most budgeting apps want your data on their servers, charge monthly fees, or require account creation. Budget App is different:

Feature	Budget App	Typical Apps
Cost	Free forever	$5-15/month
Privacy	100% local storage	Cloud-based
Account Required	No	Yes
Internet Required	No (after download)	Yes
Data Ownership	You own it all	They own it
Ads	None	Often yes

Your financial data never leaves your device. Export it, back it up, delete it—you're in complete control.

---

Features

Core Budgeting

• Budget Projections — See your finances up to 12 months ahead
• Running Balance — Day-by-day breakdown of every transaction
• Lowest Balance Alerts — Identify cash flow danger zones by month
• Multi-frequency Income — Weekly, bi-weekly, monthly, or one-time income sources

Expense Management

• Recurring Bills — Set it once, tracked every month automatically
• Ad-hoc Expenses — One-time purchases on specific dates
• Custom Categories — Create categories that match your life
• Inline Editing — Click to edit any entry directly

Smart Features

• Math Expressions — Enter 1500+250 or 2000-150 in any amount field
• Running Budget Adjustments — Override calculated values for real-world scenarios
• End-of-Month Handling — Bills set for the 31st auto-adjust for shorter months
• Bill-to-Debt Linking — Link any recurring bill directly to a debt account; the payment amount stays in sync automatically. A chain icon (🔗) marks linked bills in the table

Visualization

• Expenses Breakdown Chart — Total spending per expense over the projection period
• Category Analysis — Spending patterns grouped by category
• Debt Breakdown Donut Chart — Debt balances by type, color-coded by quality (hot reds for credit cards, neutrals for student/personal loans, cool blues for mortgages and auto loans); total debt displayed in the center
• Asset Equity Bars — For mortgages and auto loans with an estimated asset value, a horizontal bar shows debt owed (red) vs. equity held (green); a bold consolidated bar summarizes all asset-backed debts when there are two or more
• Color-Coded Balances — Green (safe), orange (caution), red (danger)

Debt Management

• Debt Summary — At-a-glance metrics: total debt, minimum and actual payments, weighted average APR, and estimated debt-free date
• Asset Equity Tracking — Enter an estimated asset value on car loans and mortgages to track equity and detect underwater loans
• Debt Classification — Seven debt types (Credit Card, Auto Loan, Personal Loan, Student Loan, Mortgage, Medical Debt, Other) with payoff projections per account

Data Control

• JSON Export — Full backup with one click
• JSON Import — Restore or transfer data instantly
• Sample Data — Try the app without entering real data
• Complete Reset — Start fresh anytime

User Experience

• Mobile Responsive — Works on phone, tablet, and desktop
• Collapsible Sections — Minimize clutter, focus on what matters
• Print Friendly — Clean printouts for offline reference
• No Loading Screens — Instant, snappy performance

Guided Setup

• "Guide Me" Wizard — A step-by-step onboarding assistant that walks new users through setting up their entire budget. Accessible from the Menu dropdown.
• 6-Step Flow — Initial Setup → Income → Debt Accounts → Monthly Expenses → One-Off Items → Review
• Budget Concierge — Add entries one at a time with friendly guidance at each step. Entries are saved immediately so nothing is lost.
• Debt-to-Bill Linking — Link monthly bills to debt accounts directly from the wizard. Payment amounts stay in sync automatically.
• Start Fresh Option — Wipe all existing data and begin from a clean slate, right from the wizard's first screen.
• Progress Tracking — A 6-step progress bar shows your position. Completed steps are clickable to jump back and review.
• Mobile Optimized — The wizard goes full-screen on mobile devices for a native app feel.

---

Quick Start

Option 1: Download and Run

git clone https://github.com/legendarycue/budget-app.git
cd budget-app
open index.html

Option 2: Direct Download

1. Download the latest release
2. Extract the ZIP file
3. Double-click index.html

That's it. No installation, no dependencies, no build process.

---

User Guide

0. Quick Start with Guide Me

The fastest way to get started:

1. Click Menu → ✨ Guide Me
2. Follow the step-by-step wizard to set up your budget
3. The wizard walks you through: start date, account balance, income, debts, bills, and one-time items
4. Click Complete when done — your budget is ready!

Tip: If you want to start completely from scratch, click "Start Fresh?" on the first screen to clear any existing data before beginning.

Tip: You can link monthly bills directly to your debt accounts during the wizard. This keeps payment amounts in sync automatically.

1. Set Your Projection Window

Start by defining when to begin tracking and how far ahead to project:

1. Open Start Date and Projection Length
2. Select your start date (today or a future date)
3. Choose projection length (1-12 months)
4. Click Set Start Date

2. Enter Your Account Balance

Set your starting point:

1. Open Checking Account Balance
2. Optionally name your account (e.g., "Bills Checking")
3. Enter your current balance
4. Click Update Checking

Tip: You can use math expressions! Enter 1500+237.50 and it calculates automatically.

3. Add Recurring Bills

These are expenses that repeat every month:

1. Open Add Bill/Expense
2. Enter the bill name (e.g., "Mortgage")
3. Set the day of month it's due (1-31)
4. Enter the amount
5. Select or create a category
6. Click Add Bill

4. Add Income Sources

Track money coming in:

1. Open Add Income
2. Enter income name (e.g., "Paycheck")
3. Enter amount per payment
4. Select frequency:
   • Weekly — Every 7 days
   • Bi-weekly — Every 14 days (most common for paychecks)
   • Monthly — Same date each month
   • One-time — Single occurrence
5. Set the start date (your next payday)
6. Click Add Income

5. Add One-Time Expenses

For non-recurring purchases:

1. Open Add Adhoc Expense
2. Enter expense name
3. Select the specific date
4. Enter amount and category
5. Click Add Adhoc Expense

6. Review Your Projection

The right side of the screen shows:

• Expenses Breakdown — Total spending per expense over the projection
• Expenses by Category — Where your money goes by type
• Lowest Balances by Month — Your tightest cash flow days
• Running Budget — Day-by-day transaction log with running balance

7. Make Adjustments

Real life doesn't match predictions. Use the Edit button on any Running Budget row to:

• Override the calculated amount for that day
• Add notes explaining the adjustment
• Handle deferrals, partial payments, or windfalls

8. Manage Debt Accounts

Track what you owe and watch your net worth improve over time:

1. Open Add Debt/Credit Account
2. Enter creditor name, debt type, balance, APR, minimum and actual monthly payments, and loan term
3. For Auto Loans and Mortgages, enter the Est. Asset Value to unlock equity tracking
4. Click Add Debt

Link a bill to a debt: When adding or editing a recurring bill, check Link to Debt Account and select the debt. The bill amount will automatically mirror the debt's actual monthly payment and stay in sync whenever the debt is edited. Deleting a debt automatically unlinks its bills and freezes the last-known amount.

Reading the Debt Breakdown chart: The donut chart below the Debt Summary card shows each debt type's share of your total debt. Color coding reflects debt quality—reds are high-cost consumer debt (credit cards, medical), blues are asset-backed loans (auto, mortgage), and neutrals sit in between (personal and student loans). The total debt is displayed in bold in the center.

Reading the Asset Equity Bars: Bars appear for mortgages and auto loans that have an estimated asset value set. The red portion is what you still owe; the green portion is your equity. If a loan balance exceeds the asset value the bar turns fully red and is labeled "underwater." A bold consolidated bar at the top summarizes all asset-backed debts when you have two or more.

Tip: The Debt Summary card also shows Est. Total Asset Value and Net Asset Equity when at least one asset-backed debt has a value set.

---

Data Management

Backing Up Your Data

Do this regularly! Your data lives only in your browser.

1. Click Menu → Export Data (JSON)
2. Save the file somewhere safe (cloud storage recommended)
3. File is named budget_data_YYYYMMDD_HHMMSS.json

Restoring Data

1. Click Menu → Import Data
2. Select your backup JSON file
3. Data loads immediately

Transferring Between Devices

1. Export from Device A
2. Transfer the JSON file (email, cloud, USB)
3. Import on Device B

Starting Fresh

1. Click Menu → Reset Data
2. Confirm the reset
3. All data is permanently deleted

Warning: Reset cannot be undone. Export first if you might want the data later.

---

Technical Details

Built With

Technology	Purpose
HTML5	Structure
CSS3	Styling & Responsiveness
JavaScript (ES6)	Application Logic
Chart.js	Data Visualization
localStorage	Data Persistence
Font Awesome	Icons

Browser Support

Browser	Supported
Chrome	✅
Firefox	✅
Safari	✅
Edge	✅
Opera	✅
IE11	❌

Data Storage

• All data stored in browser localStorage
• Storage limit: ~5-10MB (browser dependent)
• Data persists until cleared or browser data is deleted
• No data sent to external servers

File Structure

budget-app/
├── index.html          # Main application page
├── app.js              # Application logic (~2800 lines)
├── styles.css          # All styling
├── favicon.ico         # Browser tab icon
├── README.md           # This file
├── CHANGELOG.md        # Version history
├── LICENSE.md          # MIT License
└── .github/
    └── copilot-instructions.md  # AI coding assistant config

---

Contributing

Contributions are welcome! Here's how:

Reporting Bugs

1. Check existing issues first
2. Create a new issue with:
   • Clear description of the bug
   • Steps to reproduce
   • Expected vs actual behavior
   • Browser and OS information

Suggesting Features

1. Open an issue with the enhancement label
2. Describe the feature and its benefit
3. Include mockups or examples if possible

Submitting Code

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes
4. Test thoroughly
5. Commit with clear messages: git commit -m "Add: description of change"
6. Push to your fork: git push origin feature/your-feature-name
7. Open a Pull Request

Code Standards

• No frameworks—keep it vanilla JS
• Mobile-first responsive design
• Clear comments for complex logic
• Update CHANGELOG.md for any changes
• Test on Chrome, Firefox, and Safari minimum

---

Roadmap

Recently Completed

• Guided onboarding wizard ("Guide Me")
• Bill-to-Debt linking
• Debt breakdown visualization
• Asset equity tracking

Under Consideration

• Multiple checking accounts
• Savings account tracking with goals
• CSV export for spreadsheet users
• Dark mode
• Recurring expense templates
• Budget vs actual comparison
• Bill reminder notifications (with permission)

Not Planned

• ❌ User accounts or cloud sync (privacy-first philosophy)
• ❌ Bank connections or imports (security concern)
• ❌ Ads or premium tiers (free forever)

Have a feature idea? Open an issue!

---

FAQ

General

Q: Is my data really private?
A: Yes. Budget App runs entirely in your browser. No servers, no analytics, no tracking. Your data literally cannot leave your device unless you export it yourself.

Q: What happens if I clear my browser data?
A: Your budget data will be deleted. Always export backups before clearing browser data.

Q: Can I use this offline?
A: Yes! After the initial page load, everything works offline. The only external resources are Chart.js and Font Awesome (icons), which browsers typically cache.

Data

Q: How do I move my data to a new computer?
A: Export your data as JSON, transfer the file to your new computer, then import it.

Q: Why won't my file import?
A: Ensure it's a valid JSON file exported from Budget App. The filename doesn't matter—only the contents.

Q: Is there a size limit?
A: Browser localStorage is typically 5-10MB. That's enough for years of budget data.

Features

Q: What does the "Guide Me" wizard do? A: It walks you through setting up your entire budget step by step — start date, income, debts, bills, and one-time items. It's the easiest way to get started, especially if you're new to the app.

Q: What's the difference between "Start Fresh" and "Start Over" in the wizard? A: "Start Fresh" (on the first screen) erases ALL existing data in the app and gives you a completely blank slate. "Start Over" (on the review screen) only removes what you entered during the current wizard session, leaving any pre-existing data intact.

Q: Can I track multiple bank accounts? A: Currently, Budget App tracks one checking account. Multiple accounts are on the roadmap.

Q: How does Bill-to-Debt Linking work? A: When you link a recurring bill to a debt account, the bill amount automatically reflects the debt's actual monthly payment. If you update the debt payment, the bill updates too. Unlinking freezes the last-known amount so your budget stays accurate.

Q: What is the Est. Asset Value field on Auto Loans and Mortgages? A: Entering the current market value of the asset (car, home) unlocks the Asset Equity Bars visualization. The bar shows how much of the asset's value you own (equity, in green) versus what you still owe (in red). If your loan balance exceeds the asset value, the bar indicates the loan is underwater.

Q: Why don't my bills appear on the right dates?
A: Check that your projection start date is before the bill dates. Bills only show within your projection window.

Q: What if my bill is due on the 31st but the month only has 30 days?
A: Budget App automatically adjusts—the bill will appear on the last day of that month.

Troubleshooting

Q: The app isn't saving my changes!
A: Check if you're in a private/incognito window. localStorage is often disabled in private browsing.

Q: Charts aren't displaying!
A: Ensure JavaScript is enabled and try refreshing. If using an ad blocker, it may be blocking Chart.js.

Q: Something broke after an update!
A: Try importing a recent backup. If issues persist, use Reset Data and re-import.

---

License

This project is licensed under the MIT License. See LICENSE.md for details.

MIT License - Copyright (c) 2025 "Vrostbyte"

You are free to use, modify, and distribute this software.

---

Contact

Vrostbyte (Vrostbyte)

• Email: vrostbyte@proton.me
• GitHub: @vrostbyte

---

Acknowledgments

• Chart.js — Beautiful, flexible charting
• Font Awesome — Quality iconography
• Everyone who's provided feedback and bug reports

---

Budget App — Take control of your finances, privately.
Made with ☕ in Phoenix, AZ