Little House Helper

A comprehensive household expense management application designed to make splitting bills, tracking shopping trips, and managing shared costs effortless. Features multiple splitting methods, recurring expense tracking with estimates, mobile UPC scanning, customizable branding, and Discord notifications.

Features

Expense Management

• Three Splitting Methods:

  • Equal Split - Divide expenses evenly among all participants
  • Custom Percentage - Set individual percentages (must total 100%)
  • Income-Based - Split proportionally based on roommate incomes

• Recurring Expenses:

  • Set up rent, utilities, insurance, and other recurring bills
  • Weekly, biweekly, monthly, or yearly recurrence
  • Estimated amounts for budget planning
  • Custom due dates per roommate
  • Automatic expense generation on schedule
  • Monthly cost estimates to see upcoming expenses

• Flexible Expense Tracking:

  • Track bills, shopping, restaurant, rent, utilities, and more
  • Set due dates with automatic reminders
  • Mark expenses as paid with timestamps
  • "Wash" expenses (show cost without requiring payment)
  • Designate a "front person" who automatically has expenses marked as paid
  • Export expense data to Excel with monthly breakdowns

Shopping Trip Planning

• Schedule Shopping Trips:

  • One-time or recurring trips (weekly, biweekly, monthly)
  • Add items with automatic price/image scraping from URLs (Walmart, Amazon, Target)
  • Mobile UPC Scanning - Use your phone camera to scan barcodes and add items instantly
    • Automatic product name and image lookup
    • Detects if item is food for tax exemption
  • Select which roommates share each item's cost
  • Confirm scraped prices before finalizing

• Sales Tax Management:

  • Set custom tax rate per shopping trip
  • Default household tax rate
  • Food tax exemption option (common in many US states)
  • Automatic tax calculation on trip total

• Smart Reminders:

  • Automatic notifications 3, 2, and 1 day before scheduled trips
  • Due date reminders for bills and recurring expenses

• Automatic Expense Generation:

  • When trip is completed, expenses are automatically created
  • Items are grouped by shared participants
  • Payment due date calculated based on household settings

Payment System

• Payment Links & QR Codes:

  • Add CashApp, Venmo, and PayPal links
  • Automatic QR code generation for easy payment
  • Display payment info on expense details

• Payment Tracking:

  • See who owes whom at a glance
  • Track total owed, paid, and wash expenses
  • Payment history with timestamps

Discord Integration

• Rich Notifications:
  • Beautiful embedded messages
  • @ mention users when bills are due or added
  • Shopping trip reminders with countdown
  • Configurable webhook URL

User Management

• Role-Based Access:

  • Head of Household - Full access including settings and ownership transfer
  • Roommates - Can add expenses and manage their profile

• Profile Management:

  • Set income for income-based splitting
  • Set custom percentage for percentage-based splitting
  • Add Discord ID for notifications
  • Manage payment links
  • Export personal expense history when moving out

• Household Ownership:

  • Transfer household ownership to another member
  • Useful when the original head moves out

UI/UX

• Customizable Branding:

  • Set custom site title, logo, and favicon
  • Choose primary and secondary colors
  • Name your household
  • Make it your own!

• Multi-Currency Support:

  • USD, EUR, GBP, CAD, AUD, JPY, INR, MXN, BRL, ZAR
  • Automatic currency formatting
  • Locale-appropriate number formatting
  • Symbol display based on currency

• Beautiful Interface:

  • Modern, clean design with Tailwind CSS
  • Fully responsive and mobile-friendly
  • Light, Dark, and System theme modes
  • Smooth transitions and animations
  • Camera access for UPC scanning on mobile

• Dashboard:

  • Quick overview of expenses owed and paid
  • Monthly cost estimates from recurring expenses
  • Payment summary showing who to pay
  • Roommate list

Tech Stack

Backend

• Node.js & Express
• TypeScript
• MongoDB & Mongoose
• JWT Authentication
• Bcrypt for password hashing
• Axios & Cheerio for web scraping
• QRCode for payment QR generation
• Node-cron for scheduled reminders
• Multer for file uploads
• ExcelJS for data export
• UPC/Barcode product lookup APIs

Frontend

• React 18 with TypeScript
• Vite for fast development
• Tailwind CSS for styling
• Zustand for state management
• React Router for navigation
• Axios for API calls
• React Hot Toast for notifications
• React Calendar for trip scheduling
• html5-qrcode for UPC/barcode scanning

Installation

Option 1: Docker (Recommended)

The easiest way to get started! Requires Docker and Docker Compose.

# Configure environment
cp .env.docker .env
nano .env  # Edit with your settings

# Build and start
./docker-deploy.sh build
./docker-deploy.sh deploy-local

# Access at http://localhost:3000

See DOCKER.md for complete Docker deployment guide including production Docker Swarm setup.

Option 2: Manual Installation

Prerequisites

• Node.js 18+ and npm
• MongoDB (local or cloud instance)

Backend Setup

1. Navigate to the backend directory:

cd backend

2. Install dependencies:

npm install

3. Create a .env file:

cp .env.example .env

4. Edit .env with your configuration:

PORT=5000
MONGODB_URI=mongodb://localhost:27017/rm-expense-splitter
JWT_SECRET=your_secure_random_string_here
NODE_ENV=development
FRONTEND_URL=http://localhost:3000

5. Start MongoDB (if running locally):

mongod

6. Start the backend server:

npm run dev

The API will be available at http://localhost:5000

Frontend Setup

1. Navigate to the frontend directory:

cd frontend

2. Install dependencies:

npm install

3. (Optional) Create a .env file:

VITE_API_URL=http://localhost:5000/api

4. Start the development server:

npm run dev

The app will be available at http://localhost:3000

Usage

First Time Setup

1. Create a Household:

   • Visit http://localhost:3000/register
   • Enter your name, email, password, and household name
   • You'll be registered as the head of household

2. Add Roommates:

   • Go to the Roommates page
   • Click "Add Roommate"
   • Provide their name, email, and initial password

3. Configure Settings (Head of Household):

   • Go to Settings
   • Choose your expense splitting method
   • Set payment due days for shopping trips
   • (Optional) Set a front person who auto-pays bills
   • (Optional) Add Discord webhook URL for notifications

4. Set Up Profiles:

   • Each roommate should log in and go to Profile
   • Add income (for income-based splitting)
   • Set custom percentage (for percentage splitting)
   • Add payment links (CashApp, Venmo, PayPal)
   • Add Discord ID for notifications
   • Generate QR codes for payment links

Adding Expenses

1. Go to the Expenses page
2. Click "Add Expense"
3. Fill in:
   • Description
   • Amount
   • Category (bill, shopping, restaurant, other)
   • Who paid for it
   • Due date (optional)
   • Whether it's a wash expense
   • Which roommates should split it (default: all)

Creating Shopping Trips

1. Go to Shopping Trips

2. Click "Create Shopping Trip"

3. Set:

   • Trip name
   • Date
   • Recurrence (none, weekly, biweekly, monthly)

4. Add items to the trip:

   • Enter item name and price, OR
   • Paste a product URL (Walmart, Amazon, Target)
   • System will try to scrape price and image
   • Select which roommates share this item

5. Complete the trip:

   • When shopping is done, click "Complete Trip"
   • Select who paid for everything
   • Expenses will be automatically created

Discord Setup

1. Create a Discord webhook:

   • Go to your Discord server settings
   • Integrations → Webhooks → New Webhook
   • Copy the webhook URL

2. Add webhook to household:

   • Go to Settings (head of household only)
   • Paste webhook URL
   • Save

3. Add Discord IDs:

   • Each roommate should go to Profile
   • Add their Discord user ID
   • To find ID: Enable Developer Mode in Discord, right-click your name, Copy ID

Security Features

• Password Security:

  • Passwords hashed with bcrypt
  • Minimum 6 character requirement
  • Admin password reset with temporary passwords
  • Forced password change after reset

• Two-Factor Authentication (TOTP):

  • Optional 2FA using authenticator apps (Google Authenticator, Authy, etc.)
  • QR code setup for easy configuration
  • 10 backup codes for emergency access
  • Time-based one-time passwords (TOTP) with 60-second window

• Access Control:

  • JWT tokens for authentication
  • Role-based access control (Head vs Roommate)
  • Protected API endpoints
  • Temporary tokens for password resets

• Additional Security:

  • CORS configuration
  • Input validation and sanitization
  • Secure session management

Theme System

The app supports three theme modes:

• Light Mode - Bright, clean interface
• Dark Mode - Easy on the eyes for night use
• System Mode - Automatically matches your OS preference

Theme preference is saved in localStorage and persists across sessions.

Mobile Support

The entire application is fully responsive and works great on:

• Mobile phones
• Tablets
• Desktop computers
• Ultra-wide monitors

Contributing

This is a personal project, but feel free to fork and customize for your own use!

License

LGPL-3.0

Development

This project was developed with assistance from AI.

Acknowledgments

Built with love for roommates who want a collaborative housing environment!

---

Maintained with love, belly rubs and Estradiol by Puppygirl Labs

Made with love for roommates everywhere