Budget Weekly

A web application for tracking weekly expenses and managing your budget with secure authentication.

Overview

Budget Weekly helps you monitor your spending habits by tracking expenses week by week. The app alerts you when you've exceeded your budget and automatically adjusts your available budget for the following week by deducting overspending.

Features

Core Functionality

• Multi-User Support: Each user has their own isolated budget data and settings
• Secure Authentication: Username and password-protected access with bcrypt encryption
• Expense Registration: Add expenses with description, amount, category, and date
• Weekly Budget Tracking: Set a weekly budget limit and monitor spending in real-time
• Budget Overflow Management: Automatically carry over excess spending to the next week, reducing your available budget
• Expense History: View all registered expenses organized by week
• Budget Status: Visual indicators showing if you're within budget, approaching the limit, or over budget

User Interface

• Login Page: Secure username and password authentication

• Dashboard View:

  • Current week's budget status (spent vs. available)
  • Quick expense entry form
  • Visual progress bar showing budget usage
  • Warning alerts for budget overruns

• Expense Management:

  • List of all expenses for the current week
  • Edit or delete existing expenses
  • Filter expenses by category or date

• Weekly Summary:

  • View expenses grouped by week
  • See how previous weeks' overspending affects current budget
  • Track spending patterns over time

Data Management

• Multi-User Backend: Each user's data stored in /data/<username>/
• Data Persistence: Expenses and budget settings are preserved between sessions
• Authentication: JWT-based token authentication with 7-day expiration
• User Isolation: Complete data separation between users

Technical Stack

• Frontend: Vue.js 3 (Composition API)
• Backend: Node.js with Express
• Authentication: JWT tokens with bcrypt password hashing
• Storage: JSON file-based storage
• Styling: Bootstrap 5
• Build Tool: Vite
• Deployment: Docker with nginx reverse proxy

Quick Start

Prerequisites

• Node.js 18+
• npm

Setup

1. Clone the repository

   git clone <repository-url>
   cd budget-weekly
   

2. Install dependencies

   npm install
   

3. Create your first user account

   node scripts/create-user.js <username> <password>
   

   Example: node scripts/create-user.js alice mySecurePassword

   This creates the user directory and initial data files.

4. Configure environment (optional)

   cp .env.example .env
   

   Edit .env for custom JWT secret:

   JWT_SECRET=your-jwt-secret-key-change-in-production
   

5. Run in development mode

   npm run dev:all
   

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:3001

6. Login

   • Open http://localhost:3000
   • Enter your username and password

Docker Deployment

1. Create user account(s)

   node scripts/create-user.js <username> <password>
   

2. Configure environment (optional)

   cp .env.example .env
   # Edit .env with your JWT secret
   

3. Build and run

   docker-compose up -d
   

   • Access at http://localhost:8080

Budget Logic

1. User sets a base weekly budget (e.g., $500)
2. Each week starts with: Available Budget = Base Budget - Previous Week Overspending
3. As expenses are added, the remaining budget decreases
4. If week ends with overspending (e.g., -$50), next week starts with $450 instead of $500
5. If week ends under budget, the following week starts fresh with the full base budget

Data Structure

User Directory Structure

Each user has an isolated directory in /data/<username>/:

data/
└── alice/
    ├── _meta.json      # Password hash and metadata
    ├── expenses.json   # User's expense records
    └── settings.json   # Budget settings and preferences

Expense Object

{
  id: string,
  description: string,
  amount: number,
  category: string,
  date: Date,
  weekNumber: number,
  year: number
}

Settings Object

{
  baseWeeklyBudget: number,
  categories: string[],
  currency: string
}

User Management

Creating Users

See USER_MANAGEMENT.md for detailed instructions on:

• Creating new user accounts
• Password management
• User deletion
• Migrating existing data
• Security best practices

Quick command:

node scripts/create-user.js <username> <password>

Getting Started

Prerequisites

• Node.js (v16 or higher)
• npm (v7 or higher)

Installation

npm install

Development

npm run dev

Build for Production

npm run build

Future Enhancements

• Category-based budget limits
• Monthly and yearly statistics
• Charts and graphs for spending visualization
• Recurring expenses
• Multiple budget profiles (personal, household, etc.)
• Dark mode
• PWA support for offline usage