Budget_my

Comprehensive budget tracking tool designed for financial clarity, not complexity. Semi-monthly paycheck scheduling, intelligent debt management, and a clear path to financial freedom.

🎯 The Problem

Most budgeting tools fall into two traps:

• Too simple — Basic spreadsheets that can't handle real-world complexity
• Too complex — Enterprise dashboards that overwhelm rather than clarify

Real people need something different:

• Semi-monthly paychecks (15th + end of month)
• Multiple debt types with different rules
• "What do I pay first?" clarity when money is tight

💡 The Solution

A domain-first budgeting tool that understands how money actually works:

• Paycheck scheduling with business day rules
• Debt-specific modules (student loans, credit cards, BNPL, device loans)
• Intelligent recommendations when you're in financial distress
• Avalanche vs Snowball strategy comparison

✨ Features

Feature	Description
📅 Semi-monthly Scheduling	15th + end-of-month with business day rules
💳 Multi-debt Support	Student loans, credit cards, BNPL, device loans
🎯 Strategy Comparison	Avalanche vs Snowball payoff projections
⚠️ Overdue Management	Roll-forward logic with fee tracking
📊 What-If Scenarios	Model different payoff strategies
🔴 Red Mode Alerts	Smart recommendations when cash is tight
📈 Interest Analysis	Daily vs monthly accrual calculations

🛠️ Tech Stack

Technology	Purpose
Python 3.11+	Core runtime
Streamlit	Interactive UI
Pydantic	Data validation
PyYAML	Configuration

🏗️ Architecture

budget_my/
├── app.py                      # Streamlit entry point
├── budget_core/               # Core business logic
│   ├── models.py              # Pydantic data models
│   ├── calendar_rules.py      # Business day logic
│   ├── payday_scheduler.py    # Paycheck scheduling
│   ├── overdue_engine.py      # Past-due management
│   ├── interest/              # Interest calculations
│   │   ├── daily.py          # Daily accrual (high-interest)
│   │   └── monthly.py        # Standard APR
│   └── importers/             # Data import modules
├── ui/                        # Streamlit components
│   └── components/
│       ├── dashboard.py       # Main dashboard
│       ├── planner.py         # Payment planner
│       ├── debts.py           # Debt management
│       └── what_if.py         # Scenario modeling
├── config/                    # YAML configuration
│   ├── settings.yaml          # App settings
│   └── categories.yaml        # Expense categories
└── sim/                       # Simulation engines
    ├── aggregated_payoff.py   # Debt payoff projections
    └── monte_carlo.py         # Scenario simulations

📊 Supported Debt Types

Type	Features
Student Loans	Sallie Mae, Nelnet with servicer-specific rules
Credit Cards	APR, late fees, over-limit handling
Personal Loans	Fixed payment schedules
BNPL	Affirm, Zip, Sezzle installments
Device Loans	iPhone/Apple Watch with promo credits
High-Interest	Daily accrual loans (BisonGreen-style)

🎯 Key Business Rules

Paycheck Scheduling

• 15th paycheck: If weekend/holiday → previous business day
• End-of-month: Last business day of month
• Bonus handling: Configurable gross→net calculations

Debt Prioritization

1. Past Due (avoid fees/collections)
2. Due Before Next Payday
3. Strategy-Based (Avalanche or Snowball)

Recommendations Engine

• Red mode triggers when obligations exceed available cash
• Smart suggestions: Pause subscriptions, reduce variable expenses
• Fee prevention: Countdown warnings for upcoming penalties

🚀 Quick Start

# Clone and install
git clone https://github.com/Mitzseen/budget-my.git
cd budget_my
pip install -e .

# Run the app
streamlit run app.py

📁 Data Import

Supports importing from:

• Excel spreadsheets (existing budget data)
• CSV files (transaction history)
• Manual entry (Bills.txt format)

🎯 Product Decisions

Decision	Rationale
Semi-monthly first	Most salaried workers get paid this way
Debt-type modules	Each debt type has different rules
Red mode alerts	Proactive guidance > reactive tracking
Streamlit UI	Fast iteration, Python-native

📈 What Makes This Different

Most budgeting apps track what happened. Budget_my helps you plan what to do next:

1. Paycheck arrives → See exactly what to pay
2. Money is tight → Get prioritized recommendations
3. Planning ahead → Model scenarios before committing

📄 License

PolyForm Noncommercial License 1.0.0

You may view and use this software for personal, educational, and noncommercial purposes. Commercial use is prohibited. See LICENSE for full terms.

---

Built by someone who actually manages multiple debts and needed a tool that understands real-world financial complexity.