💰 BillWise - Complete Bill, Subscription & Expense Tracker

A comprehensive Python Flask web application to track bills, subscriptions, memberships, and one-time expenses. Features payment history tracking, file uploads, custom categories, and a beautiful dark theme UI. Access from your phone or desktop to never miss a payment again!

🚀 Quick Start with Docker (Recommended)

cd /home/docker/appdata/billy
docker-compose up -d

Access at: http://YOUR_SERVER_IP:5000

✨ Features

✅ Bill & Subscription Management

• Three Payment Types:
  • 📄 Bills - Utilities, mortgage, insurance, taxes
  • 📱 Subscriptions - OpenAI, iCloud, Netflix, Spotify, SaaS services
  • 💪 Memberships - Gym, clubs, professional associations
• Flexible Recurrence: Set any frequency (every X days/weeks/months/years)
  • Every 2 weeks for cleaners
  • Every 3 months for quarterly bills
  • Any custom schedule you need
• Bill Details: Due dates, amounts, categories, payment URLs, auto-pay status
• Smart Filters: View all, bills only, subscriptions only, memberships only, due today, due soon
• Visual Status Badges: Overdue, Due Today, Due Soon
• Edit from Detail Page: Update bill information directly from the detail view
• Inline Editing: Quick edits without leaving the dashboard

💳 Payment History Tracking

• Complete Payment Records: Import 1,300+ payments from Chronicle app
• Professional Table Layout: Payment date, amount, method, notes
• Statistics: Total payments, total paid, average payment
• Record New Payments: Add payments as you make them
• Delete Payments: Remove incorrect entries

💰 Expense Tracking

• One-Time Purchases: Track appliances, home projects, repairs
• Detailed Information:
  • Purchase details (vendor, date, amount)
  • Model and serial numbers
  • Warranty tracking (start/end dates, notes)
  • Location in home
• Custom Categories: Vacation, appliances, electronics, furniture, etc.
• Spending Analytics: Year total, all-time total, item count
• Warranty Alerts: See what's under warranty

🏥 Health Claims Tracking (NEW!)

• Insurance Claims Management: Track health insurance claims and reimbursements
• Family Members: Manage claims for yourself and family members
  • Track relationship (self, spouse, child, dependent)
  • Store insurance member ID and provider info
• Pre-Defined Categories: 9 built-in categories with annual limits
  • Prescription, Dental, Optical, Massage, Physiotherapy
  • Chiropractor, Occupational Therapy, Psychology, Acupuncture
• Visual Progress Tracking: Color-coded progress bars for each category
  • Green (<50% used), Yellow (50-80%), Red (>80%)
  • See remaining balance at a glance
• Dual Statistics: View claims by category AND by family member
• Complete Claim Lifecycle: Track from submission to payment
  • Status tracking: Pending → Submitted → Approved → Paid
  • Record billed, approved, and paid amounts
  • Track deductibles and claim numbers
• File Attachments: Upload EOBs (Explanation of Benefits), receipts, and invoices
• Year Navigation: Review historical claims and track annual usage

📎 File Upload & Management

• Upload Receipts & Invoices: Attach files to both expenses AND bills
• Supported Files: PDF, DOC, DOCX, TXT, PNG, JPG, JPEG, GIF (16MB max)
• Multiple Attachments: Upload as many files as needed per item
• View & Download: Access files anytime from any device
• Secure Storage: Files stored safely in Docker volumes

🗂️ Category Management

• Custom Categories: Create unlimited categories with custom colors
• Organize Everything: Bills, subscriptions, and expenses
• Visual Color Coding: Easy identification at a glance
• Flexible Assignment: Assign categories to any item

🎨 User Interface

• Mobile-First Design: Optimized touch-friendly interface for phones and tablets
• Dark Theme: Beautiful dark theme optimized for reduced eye strain
• Responsive Design: Perfect on phone, tablet, and desktop
• Modern Layout: Clean, intuitive navigation with bottom navigation on mobile
• Fast Performance: Smooth interactions and quick loading
• Notification System: Success/error notifications for all actions
• Touch Gestures: Swipe and tap optimized for mobile devices

🔐 Security & Authentication

• User Authentication: Secure session-based authentication
• Password Hashing: Werkzeug security
• Protected Routes: All data secured behind login
• File Security: User-specific file access only

🛠️ Technologies Used

• Backend: Python Flask 3.0
• Database: SQLite3 with WAL mode for improved concurrency
• Security: Werkzeug password hashing, session-based auth
• Frontend: HTML5, CSS3, Vanilla JavaScript
• Design: Mobile-first responsive design with custom dark theme
• Deployment: Docker & Docker Compose
• Performance: Optimized database connections and query handling

📋 Prerequisites

• Docker & Docker Compose (recommended) OR
• Python 3.12+ with Flask installed

🐳 Installation & Setup

Option 1: Docker (Easiest)

1. Start the application:

   cd /home/docker/appdata/billy
   docker-compose up -d
   

2. Access the app: http://YOUR_SERVER_IP:5000

3. View logs (optional):

   docker-compose logs -f
   

4. Stop the application:

   docker-compose down
   

Option 2: Direct Python (Without Docker)

See INSTALL.md for detailed installation instructions including:

• System Python setup
• Virtual environment setup
• Manual installation steps
• Dependencies and requirements

First Time Setup - Onboarding Wizard

BillWise includes a comprehensive onboarding wizard that runs automatically when you first access the application (when no users exist in the database).

The onboarding wizard will guide you through:

1. Account Creation:

   • Username, email, and password (with strength indicator)
   • Real-time password matching validation

2. Preferences:

   • Timezone selection (North America, Europe, Asia/Pacific)
   • Currency (USD, CAD, EUR, GBP, AUD, JPY, CNY, INR)
   • Date format (MM/DD/YYYY, DD/MM/YYYY, YYYY-MM-DD)
   • Notification reminder days (how many days before due date)

3. Notification Settings (Optional):

   • ntfy.sh topic for push notifications
   • ntfy server URL (default: https://ntfy.sh)
   • SMTP settings for email notifications

Environment Variable Pre-population:

You can pre-populate onboarding defaults using environment variables in docker-compose.yml:

environment:
  # Onboarding Defaults
  - ADMIN_USERNAME=admin
  - ADMIN_EMAIL=admin@example.com
  - DEFAULT_TIMEZONE=America/Regina
  - DEFAULT_CURRENCY=CAD
  - DEFAULT_DATE_FORMAT=YYYY-MM-DD
  - DEFAULT_REMINDER_DAYS=3

  # Notification defaults
  - NTFY_TOPIC=billwise-notifications
  - NTFY_URL=https://ntfy.sh

  # SMTP defaults
  - SMTP_HOST=smtp.gmail.com
  - SMTP_PORT=587
  - SMTP_USER=your-email@gmail.com

After completing onboarding, you'll be automatically logged in and ready to start tracking your bills!

🔄 Updating BillWise

If you are updating from an older version of BillWise, you may need to apply database migrations to support new features.

Migrating to Enable PWA & Push Notifications

Recent updates introduced Progressive Web App (PWA) capabilities, including web push notifications. These features require changes to the database schema. If you are updating an existing installation, you must run the following migration scripts in order to avoid errors.

1. Pull the latest code from your repository.

2. Stop your Docker container: docker-compose down

3. Run the migration scripts using docker-compose run. This ensures they execute within the correct environment.

   • First, add the push_subscriptions table:

     docker-compose run --rm billwise python3 migrate_add_push_subscriptions.py
     

   • Next, add notification settings to the users table:

     docker-compose run --rm billwise python3 migrate_add_notification_settings_to_users.py
     

4. Restart your application: docker-compose up -d --build

Your database is now updated to support the latest features.

📊 Real-World Example

Imported from Chronicle App

• ✅ 13 bills automatically imported
• ✅ 1,302 payment records imported
• ✅ Payment history dating back to 2013
• ✅ Complete financial tracking in one place

Track Everything

Bills: Mortgage, utilities, taxes, insurance (147+ payments each)
Subscriptions: OpenAI ($20/mo), iCloud ($0.99/mo), Netflix, Spotify
Memberships: Gym, Costco, professional associations
Expenses: Samsung Fridge ($2,499 - receipt, warranty, photos attached)
Vacation: Hawaii 2025 ($5,000 - all receipts and confirmations)

🐋 Docker Compose Configuration

Here's a complete sample docker-compose.yml with all configuration options:

version: '3.8'

services:
  billwise:
    build: .
    container_name: billwise
    ports:
      - "5000:5000"
    volumes:
      - ./billwise.db:/app/billwise.db
      - ./uploads:/app/uploads
    environment:
      - SECRET_KEY= # Set a random secret key here

      # --- Onboarding Defaults (Optional) ---
      - ADMIN_USERNAME=
      - ADMIN_EMAIL=
      - DEFAULT_TIMEZONE=America/Regina
      - DEFAULT_CURRENCY=USD
      - DEFAULT_DATE_FORMAT=MM/DD/YYYY
      - DEFAULT_REMINDER_DAYS=3

      # --- Notification Settings (Optional) ---
      # See instructions below for setup
      - SMTP_ENABLED=false
      - SMTP_HOST=
      - SMTP_PORT=587
      - SMTP_USERNAME=
      - SMTP_PASSWORD=
      - SMTP_FROM=
      - SMTP_USER=

      - NTFY_ENABLED=false
      - NTFY_URL=https://ntfy.sh
      - NTFY_TOPIC=
      - NTFY_TOKEN=

      # - VAPID_PUBLIC_KEY=
      # - VAPID_PRIVATE_KEY=
    restart: unless-stopped
    extra_hosts:
      - "host.docker.internal:host-gateway"

⚙️ Configuration Notes

• SECRET_KEY (Required): Generate a random secret key for session security and paste it here.

  python3 -c "import secrets; print(secrets.token_hex(32))"
  

• volumes: Your database (billwise.db) and file uploads (uploads/) are safely stored on your host machine.
• ports: The app is accessible at port 5000. Change the first number if you have a port conflict (e.g., "8080:5000").

🔔 Notification Setup

BillWise supports three types of notifications. You can enable one or more by setting the environment variables in your docker-compose.yml.

1. ntfy.sh (Recommended)

Get instant push notifications via the open-source ntfy.sh service.

• NTFY_ENABLED: Set to true
• NTFY_URL: The URL of the ntfy server (e.g., https://ntfy.sh)
• NTFY_TOPIC: The topic name for your notifications (e.g., billwise-reminders)
• NTFY_TOKEN: Optional token for private, self-hosted servers.

2. Email (SMTP)

Receive detailed email reminders. Works with providers like Gmail, Outlook, etc.

• SMTP_ENABLED: Set to true
• SMTP_HOST: Your email provider's SMTP server (e.g., smtp.gmail.com)
• SMTP_PORT: Typically 587 (for TLS) or 465 (for SSL)
• SMTP_USERNAME: Your full email address
• SMTP_PASSWORD: Your email password or an app-specific password (recommended for Gmail/Outlook)
• SMTP_FROM: The "From" address for emails, usually the same as your username.

3. Web Push Notifications (PWA)

Get native browser notifications on your phone or desktop. This is required for the "Add to Home Screen" PWA experience.

Setup Steps:

1. Install web-push: You'll need Node.js installed on your local machine (not the server) to generate keys.

   npm install -g web-push
   

2. Generate VAPID Keys: Run this command in your terminal.

   web-push generate-vapid-keys
   

3. Copy and Paste Keys: The command will output a Public Key and a Private Key. Copy these into your docker-compose.yml:

     - VAPID_PUBLIC_KEY=BC... # Paste Public Key here
     - VAPID_PRIVATE_KEY=7_d... # Paste Private Key here
   

4. Restart BillWise: docker-compose up -d --force-recreate to apply the new settings.

📁 Project Structure

billy/
├── app.py                      # Main Flask application
├── init_db.py                  # Database initialization
├── requirements.txt            # Python dependencies
├── docker-compose.yml          # Docker configuration
├── Dockerfile                  # Docker image
├── templates/                  # HTML templates
│   ├── dashboard.html         # Main dashboard
│   ├── bill_form.html         # Add/edit bills
│   ├── bill_detail.html       # Bill details & payment history
│   ├── expenses.html          # Expense list
│   ├── expense_form.html      # Add/edit expenses
│   ├── expense_detail.html    # Expense details & attachments
│   └── categories.html        # Category management
├── static/                     # Static assets
│   ├── css/style.css          # Dark theme styles
│   └── js/                    # JavaScript files
│       ├── dashboard.js
│       ├── bill_detail.js
│       ├── expenses.js
│       └── expense_detail.js
├── uploads/                    # File uploads (receipts, invoices)
│   ├── bills/                 # Bill attachments
│   └── expenses/              # Expense attachments
├── billwise.db                # SQLite database
├── import_chronicle.py        # Import from Chronicle CSV
├── import_payment_history.py # Import payment records
└── README.md                  # This file

📱 Accessing from Your Phone

1. Make sure your phone is on the same network as your server
2. Find your server's IP address:

   hostname -I
   

3. Open your phone's browser and navigate to: http://SERVER_IP:5000
4. (Optional) Add to your phone's home screen for app-like experience

📥 Import Your Existing Data

From Chronicle App (Mac)

# Export from Chronicle to CSV
# Place CSV file in billy directory
python3 import_chronicle.py
python3 import_payment_history.py

This imports:

• All bills with due dates and amounts
• Complete payment history (1,300+ records)
• Notes and payment methods
• Historical data dating back years

🔒 Security Notes

• Change the SECRET_KEY in docker-compose.yml or set it as an environment variable
• Use HTTPS in production (consider using Nginx as a reverse proxy)
• Regularly backup your billwise.db file and uploads/ directory
• Keep Flask and dependencies updated
• Files are user-specific and require login to access

🐛 Troubleshooting

Can't access from phone?

• Ensure port 5000 is open in your firewall
• Check that you're using the correct server IP address
• Verify your phone is on the same network

Database errors?

• Delete billwise.db and run python3 init_db.py again
• Check file permissions on the database file

Docker issues?

• Check logs: docker-compose logs
• Restart: docker-compose restart
• Rebuild: docker-compose up --build

🎯 Use Cases

Household Bills

• Track all utilities, mortgage, insurance
• View payment history for tax time
• Never miss a due date

Subscription Management

• See all subscriptions in one place
• Track streaming services, SaaS tools
• Audit and cancel unused subscriptions

Expense Tracking

• Record appliance purchases with warranties
• Track home renovation projects
• Organize vacation expenses with receipts

Financial Planning

• Calculate monthly spending
• View payment trends over time
• Budget for upcoming expenses

📚 Documentation

Additional documentation is available in the docs/ directory:

• docs/FILE_UPLOADS_GUIDE.md - Complete guide to uploading and managing files
• docs/IMPORT_GUIDE.md - Importing data from Chronicle and other sources
• docs/TESTING_GUIDE.md - Guide for testing the application
• docs/FEATURES_UPDATE.md - Recent feature additions and improvements
• ROADMAP.md - Future features and development plans
• INSTALL.md - Detailed installation instructions

🧪 Testing

BillWise includes end-to-end tests using Playwright for automated testing and visual verification.

Quick Start

# Install Playwright
npm install -D @playwright/test
npx playwright install

# Run all tests
npx playwright test

# Run in headed mode (watch the browser)
npx playwright test --headed

# View test report
npx playwright show-report

What's Tested

• ✅ Onboarding Flow - Complete setup wizard including validation
• ✅ Authentication - Login/logout and session management
• ✅ Dashboard Navigation - Settings page and main navigation
• ✅ Form Validation - Password strength and matching
• ✅ Visual Verification - Screenshots for UI regression testing

Test Files

• tests/onboarding.spec.js - Onboarding flow and settings verification
• playwright.config.js - Playwright configuration
• tests/README.md - Detailed testing documentation

For complete testing documentation, see tests/README.md.

📄 License

This project is open source and available under the MIT License.

🙏 Credits

Built with:

• Python Flask 3.0
• SQLite3
• Vanilla JavaScript
• Love and attention to detail ❤️

---

Made with ❤️ for complete financial tracking on phone and desktop

Track bills • Manage subscriptions • Record expenses • Upload receipts • Never miss a payment