Budget Management

OneLibro's budget management feature helps you track your spending goals across different categories. Set monthly, weekly, or yearly budgets and automatically track your progress as transactions sync from your connected accounts.

Overview

The budget management system allows you to:

Create unlimited budgets for different spending categories
Track spending automatically from connected bank accounts
Set budget periods (weekly, monthly, or yearly)
Get visual progress indicators with color-coded alerts
Receive email alerts when approaching budget limits (80% and 100%)
Edit and manage existing budgets
View spending trends and daily averages

Budgets are designed to help you stay on track with your financial goals by providing real-time visibility into your spending patterns.

Creating a Budget

Go to the Budgets page from the main navigation
Click the "New Budget" button
Fill out the budget creation form

Budget Form Fields

1. Budget Name (Required)

A descriptive name for your budget to help you identify it.

Examples:

"Monthly Groceries"
"Entertainment"
"Weekly Dining Out"
"Yearly Travel Budget"

Best Practices:

Use clear, descriptive names
Include the period if managing multiple budgets for the same category
Keep names concise for better display on mobile

2. Category (Required)

The spending category this budget applies to. OneLibro matches transactions to budgets based on category.

Available Categories:

Food and Drink
Groceries
Shopping
Transportation
Travel
Entertainment
Bills & Utilities
Healthcare
Personal Care
Education
Home
Other

How Category Matching Works:

Transactions are automatically categorized by Plaid when synced
Budget tracking uses partial matching (e.g., a budget for "Food" will track "Food and Drink" transactions)
Manual transactions use the categories you assign them

3. Budget Amount (Required)

The spending limit for this budget period.

Input Format:

Enter amount in dollars (e.g., 500.00)
Minimum: $0.01
No maximum limit
Amounts are stored as cents internally for precision

Quick Amount Buttons: When creating a new budget, you can use preset amounts:

$50
$100
$200
$500
$1,000

4. Budget Period (Required)

How often the budget resets and tracks spending.

Available Periods:

Period	Resets	Use Case
Weekly	Every Monday	Short-term spending like dining out, entertainment
Monthly	1st of each month	Most common budgets like groceries, utilities, shopping
Yearly	January 1st	Infrequent expenses like travel, insurance, gifts

Period Start Dates:

Weekly: Monday at 12:00 AM
Monthly: 1st of the month at 12:00 AM
Yearly: January 1st at 12:00 AM

Example: Creating a Budget

// Budget data structure
{
  name: "Monthly Groceries",
  category: "Groceries",
  amount: 50000, // $500.00 in cents
  period: "monthly",
  user_id: "user-uuid",
  is_active: true
}

Step-by-Step:

Click "New Budget"
Enter name: "Monthly Groceries"
Select category: "Groceries"
Enter amount: 500
Select period: "Monthly"
Click "Create Budget"

You'll be redirected to the budgets page where your new budget will appear with 0% spent initially.

Viewing Budgets

Budget List Page

The budgets page (/finance/budgets) shows all your active budgets with:

For Each Budget:

Header:
- Budget name
- Status badge (Good, On Track, Almost There, Over Budget)
- Category and period
- Edit and delete buttons
Progress Bar:
- Amount spent vs total budget
- Percentage used
- Remaining amount (or overage amount)
- Color-coded progress indicator
Stats:
- Daily average spending
- Spending trend (Low/High)
Warnings:
- Alert when you've used 80%+ of your budget
- Error message when you've exceeded 100%

Budget Status Indicators

Budgets display status badges based on how much you've spent:

Status	Percentage	Color	Meaning
Good	0-49%	Green	Well within budget
On Track	50-79%	Yellow	Moderate spending, on track
Almost There	80-99%	Orange	Approaching limit, slow down
Over Budget	100%+	Red	Exceeded budget limit

Progress Bar Colors

The visual progress bar changes color based on spending:

// Progress bar color logic
if (percentage >= 100) return 'bg-red-500';    // Over budget
if (percentage >= 80)  return 'bg-orange-500'; // Close to limit
if (percentage >= 50)  return 'bg-yellow-500'; // Moderate
return 'bg-green-500';                         // Good

Budget Calculations

Spent Amount

Calculated by summing all expense transactions in the current period that match the budget category.

Calculation Logic:

Get the period start date (Monday for weekly, 1st for monthly, Jan 1 for yearly)
Filter transactions:
- Transaction date >= period start
- Transaction amount > 0 (expenses only, not income)
- Category matches budget category (partial match, case-insensitive)
Sum all matching transaction amounts

Example:

Budget: "Monthly Groceries" ($500, period: monthly)
Current date: March 15th
Period start: March 1st
Matching transactions since March 1st: $125.43 + $67.89 + $52.10 = $245.42
Spent: $245.42 (49% of $500)

Percentage Used

const percentage = Math.round((spentAmount / budgetAmount) * 100);

Examples:

Spent $245.42 of $500.00 = 49%
Spent $450.00 of $500.00 = 90%
Spent $625.00 of $500.00 = 125% (over budget)

Remaining Amount

const remaining = budgetAmount - spentAmount;

Positive remaining: You have money left in the budget
Negative remaining: You've exceeded the budget (shown as "over budget")

Display Examples:

"$254.58 remaining" (under budget)
"$125.00 over budget" (exceeded)

Daily Average

Shows your average daily spending for the current period.

const currentDay = new Date().getDate(); // Day of month (1-31)
const dailyAverage = spentAmount / currentDay;

Example (March 15th):

Spent $300 so far
Daily average: $300 / 15 = $20.00/day

tip

Use daily average to predict if you'll stay within budget. If your daily average is higher than your budget divided by days in the period, you may need to slow spending.

Editing a Budget

How to Edit

Navigate to the Budgets page
Click the Edit icon (pencil) next to the budget you want to modify
Update any fields (name, category, amount, period)
Click "Update Budget"

What You Can Edit

✅ Budget name
✅ Category
✅ Amount
✅ Period

What Happens When You Edit

Changing the amount: Immediately updates the percentage and remaining calculations
Changing the category: Budget will now track different transactions
Changing the period: Resets the period start date and recalculates spending
Spending history: Not affected; calculations use the new period start

Changing Categories

If you change the category, the budget will start tracking different transactions. Make sure this is what you want before saving.

Deleting a Budget

How to Delete

Navigate to the Budgets page
Click the Delete icon (trash) next to the budget
Confirm the deletion in the popup dialog

What Happens

Budget is soft-deleted (marked as is_active: false in database)
Budget no longer appears in the budgets list
Budget alerts stop being sent
Historical spending data remains intact
Deletion is permanent - you cannot undo this action

Permanent Deletion

Deleted budgets cannot be recovered. If you want to temporarily pause budget tracking, consider editing the amount to a very high value instead.

Budget Periods Explained

Weekly Budgets

Starts: Every Monday at 12:00 AM
Ends: Sunday at 11:59 PM
Best For: Variable weekly expenses like dining out, entertainment, gas
Example: "Weekly Coffee Budget" ($50/week)

Calculation:

// Get start of current week (Monday)
const now = new Date();
const dayOfWeek = now.getDay(); // 0 = Sunday, 1 = Monday, ...
const diff = now.getDate() - dayOfWeek + (dayOfWeek === 0 ? -6 : 1);
const weekStart = new Date(now.setDate(diff));

Monthly Budgets

Starts: 1st of each month at 12:00 AM
Ends: Last day of month at 11:59 PM
Best For: Most recurring expenses (groceries, utilities, shopping, subscriptions)
Example: "Monthly Groceries" ($500/month)

Calculation:

// Get start of current month
const now = new Date();
const monthStart = new Date(now.getFullYear(), now.getMonth(), 1);

Yearly Budgets

Starts: January 1st at 12:00 AM
Ends: December 31st at 11:59 PM
Best For: Infrequent or annual expenses (travel, gifts, insurance, memberships)
Example: "Yearly Travel Budget" ($3,000/year)

Calculation:

// Get start of current year
const now = new Date();
const yearStart = new Date(now.getFullYear(), 0, 1);

Empty State

If you haven't created any budgets yet, you'll see an empty state with:

Friendly message: "No budgets yet"
Call-to-action: "Create your first budget to start tracking your spending goals"
Quick "Create Budget" button

Budget Alerts

OneLibro automatically sends you email notifications when you approach or exceed your budget limits.

Alert Thresholds

Threshold	Email Sent	Alert Level
90%	⚠️ Warning email	You're approaching your budget limit
100%	🚨 Exceeded email	You've exceeded your budget

Alert Features

Automatic: No setup required, alerts are enabled by default
Daily cron job: Checks all budgets daily at 9 AM UTC
Duplicate prevention: Won't send multiple emails for the same period
Customizable thresholds: Adjust alert levels in notification settings (see Notification Preferences - coming in Phase 3)

Alert Email Contents:

Budget name and category
Current spending vs budget amount
Percentage used
Remaining amount (or overage)
Link to view budget details

Best Practices

Choosing Budget Amounts

Use Historical Data:

Go to Transactions page
Filter by category for the last 1-3 months
Calculate average monthly spending
Set budget 10-20% higher than average to account for variability

Start Conservative:

Set budgets slightly lower than you think you need
Easier to increase later than to overspend consistently
Builds good spending habits

The 50/30/20 Rule

A popular budgeting framework:

50% Needs: Essential expenses (groceries, bills, rent, utilities)
30% Wants: Discretionary spending (dining out, entertainment, shopping)
20% Savings: Emergency fund, retirement, debt repayment

Example (Monthly income: $4,000):

Needs: $2,000 (groceries $500, utilities $200, rent $1,300)
Wants: $1,200 (entertainment $300, shopping $400, dining $500)
Savings: $800 (automatically transferred to savings account)

Multiple Budgets Strategy

Granular Approach:

Create separate budgets for subcategories
Example: "Groceries" ($400), "Dining Out" ($200), "Coffee" ($50)
Pros: More visibility into specific spending
Cons: More budgets to manage

Consolidated Approach:

Create broader category budgets
Example: "Food and Drink" ($650 total)
Pros: Simpler to manage, more flexible
Cons: Less visibility into subcategory spending

Choose based on your tracking preferences and spending patterns.

Budget Review Schedule

Weekly Review (10 minutes):

Check weekly budgets on Sunday evening
Identify overspending early
Adjust spending for the following week

Monthly Review (30 minutes):

Review all budgets on the last day of the month
Update budget amounts based on actual spending
Add new budgets for categories you want to track
Remove budgets that are no longer relevant

Quarterly Review (1 hour):

Deep dive into spending patterns
Adjust budget strategy based on goals
Reassess priorities and financial goals

Tips & Tricks

Tip 1: Start Small

Don't try to budget for every category at once. Start with your top 3-5 spending categories.

Recommended First Budgets:

Groceries (usually the largest expense)
Dining & Entertainment
Shopping
Transportation
Bills & Utilities (if variable)

Tip 2: Use Visual Cues

Pay attention to budget status colors:

🟢 Green: You're doing great, maintain current pace
🟡 Yellow: On track, but monitor closely
🟠 Orange: Slow down spending in this category
🔴 Red: Stop spending in this category immediately

Tip 3: Account for Variability

Some categories have natural variability (e.g., utilities, gas, healthcare).

Solution: Set budgets 20-30% higher than average to avoid constant overage alerts.

Tip 4: Sync Before Checking

Before reviewing budgets:

Go to Accounts page
Click "Sync Transactions" on each account
Wait for sync to complete
Then check budget progress

This ensures you're seeing the most up-to-date spending data.

Tip 5: Leverage Alerts

Enable budget alerts in Settings → Notifications to get:

Email when you hit 90% of budget (customizable threshold)
Daily digest of all budget statuses
Weekly summary of spending vs budgets

Common Use Cases

Use Case 1: Controlling Dining Out

Goal: Reduce restaurant spending

Create budget: "Dining Out" ($200/month)
Enable 80% alert
When alert comes (at $160), switch to cooking at home
Track progress weekly

Expected Result: Stay under $200/month, save $100+/month compared to no budget

Use Case 2: Planning for Annual Expenses

Goal: Save for annual vacation

Create budget: "Yearly Travel" ($3,000/year)
Track all travel-related expenses
Monitor progress monthly ($250/month average)
Adjust spending in other categories if falling behind

Expected Result: Have $3,000 saved by end of year for guilt-free travel

Use Case 3: Variable Income Budgeting

Goal: Budget with inconsistent income

Calculate minimum monthly income
Set budgets at 80% of minimum to build buffer
In high-income months, don't increase budgets
Use surplus for savings or debt repayment

Expected Result: Sustainable budgets that work even in low-income months

Troubleshooting

Budget Not Tracking Transactions

Possible Causes:

Category mismatch: Transaction category doesn't match budget category
Transaction date: Transaction is from before the current period
Transaction type: Transaction is income (negative amount) not expense
Not synced yet: Recent transactions haven't synced from Plaid

Solutions:

Check transaction categories in the Transactions page
Manually categorize transactions if needed
Sync accounts to get latest transactions
Verify budget category matches transaction categories

Budget Percentage Over 100%

This is normal! Budgets can exceed 100% if you overspend.

What to do:

Immediate: Stop spending in that category
Short-term: Reduce spending in other categories to compensate
Long-term: Review if budget amount is realistic, increase if needed

Budget Keeps Resetting to Zero

Cause: Budget period has reset (new week/month/year started)

This is expected behavior. Budgets automatically reset based on their period:

Weekly: Every Monday
Monthly: Every 1st of month
Yearly: Every January 1st

Solution: This is how budgets work. Historical spending data is still available in the Transactions page.

API Reference

For developers integrating with the budget system:

Database Schema

CREATE TABLE budgets (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  name TEXT NOT NULL,
  category TEXT NOT NULL,
  amount INTEGER NOT NULL, -- Amount in cents
  period TEXT NOT NULL CHECK (period IN ('weekly', 'monthly', 'yearly')),
  is_active BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Helper Functions

Get User Budgets:

import { getUserBudgets } from '@/lib/supabase';

const budgets = await getUserBudgets(userId);
// Returns array of Budget objects

Calculate Spent Amount:

// In app/finance/budgets/page.tsx
function calculateSpent(budget: Budget, transactions: Transaction[]): number {
  const periodStart = getPeriodStartDate(budget.period);

  return transactions
    .filter((tx) => {
      const txDate = new Date(tx.transaction_date);
      const categoryMatch = tx.category?.toLowerCase().includes(budget.category.toLowerCase());
      return categoryMatch && txDate >= periodStart && tx.amount > 0;
    })
    .reduce((sum, tx) => sum + tx.amount, 0);
}

Create Budget:

import { supabase, dollarsToCents } from '@/lib/supabase';

const { data, error } = await supabase
  .from('budgets')
  .insert({
    user_id: userId,
    name: 'Monthly Groceries',
    category: 'Groceries',
    amount: dollarsToCents(500), // Convert $500 to cents
    period: 'monthly',
    is_active: true,
  });

Budget Alerts - Automated email notifications
Transactions - View and categorize transactions
Dashboard - See budget progress at a glance
Notification Preferences (coming in Phase 3) - Customize alert settings

Summary

Budget management in OneLibro provides:

✅ Flexible budgeting (weekly, monthly, yearly)
✅ Automatic transaction tracking
✅ Visual progress indicators
✅ Customizable email alerts
✅ Multiple budgets per category
✅ Real-time spending calculations
✅ Mobile-responsive design

Start creating budgets today to take control of your spending and achieve your financial goals!

Overview​

Creating a Budget​

Navigation​

Budget Form Fields​

1. Budget Name (Required)​

2. Category (Required)​

3. Budget Amount (Required)​

4. Budget Period (Required)​

Example: Creating a Budget​

Viewing Budgets​

Budget List Page​

Budget Status Indicators​

Progress Bar Colors​

Budget Calculations​

Spent Amount​

Percentage Used​

Remaining Amount​

Daily Average​

Editing a Budget​

How to Edit​

What You Can Edit​

What Happens When You Edit​

Deleting a Budget​

How to Delete​

What Happens​

Budget Periods Explained​

Weekly Budgets​

Monthly Budgets​

Yearly Budgets​

Empty State​

Budget Alerts​

Alert Thresholds​

Alert Features​

Best Practices​

Choosing Budget Amounts​

The 50/30/20 Rule​

Multiple Budgets Strategy​

Budget Review Schedule​

Tips & Tricks​

Tip 1: Start Small​

Tip 2: Use Visual Cues​

Tip 3: Account for Variability​

Tip 4: Sync Before Checking​

Tip 5: Leverage Alerts​

Common Use Cases​

Use Case 1: Controlling Dining Out​

Use Case 2: Planning for Annual Expenses​

Use Case 3: Variable Income Budgeting​

Troubleshooting​

Budget Not Tracking Transactions​

Budget Percentage Over 100%​

Budget Keeps Resetting to Zero​

API Reference​

Database Schema​

Helper Functions​

Related Features​

Summary​

Overview

Creating a Budget

Navigation

Budget Form Fields

1. Budget Name (Required)

2. Category (Required)

3. Budget Amount (Required)

4. Budget Period (Required)

Example: Creating a Budget

Viewing Budgets

Budget List Page

Budget Status Indicators

Progress Bar Colors

Budget Calculations

Spent Amount

Percentage Used

Remaining Amount

Daily Average

Editing a Budget

How to Edit

What You Can Edit

What Happens When You Edit

Deleting a Budget

How to Delete

What Happens

Budget Periods Explained

Weekly Budgets

Monthly Budgets

Yearly Budgets

Empty State

Budget Alerts

Alert Thresholds

Alert Features

Best Practices

Choosing Budget Amounts

The 50/30/20 Rule

Multiple Budgets Strategy

Budget Review Schedule

Tips & Tricks

Tip 1: Start Small

Tip 2: Use Visual Cues

Tip 3: Account for Variability

Tip 4: Sync Before Checking

Tip 5: Leverage Alerts

Common Use Cases

Use Case 1: Controlling Dining Out

Use Case 2: Planning for Annual Expenses

Use Case 3: Variable Income Budgeting

Troubleshooting

Budget Not Tracking Transactions

Budget Percentage Over 100%

Budget Keeps Resetting to Zero

API Reference

Database Schema

Helper Functions

Related Features

Summary