scott/billwise-bill-manager
Watch
1
0
Fork
You've already forked billwise-bill-manager
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
a simple web app to track bills, subscriptions and expenses.
2 commits 1 branch 0 tags 30 KiB
Find a file
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Scott Woods-Fehr 84d121b3c1 Update README.md
2025-12-15 15:56:51 +00:00
README.md Update README.md 2025-12-15 15:56:51 +00:00

README.md

billwise

a simple web app to track bills, subscriptions and expenses.

💰 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

💳 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

📎 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

  • Dark Theme: Beautiful dark theme optimized for reduced eye strain
  • Responsive Design: Perfect on phone, tablet, and desktop
  • Modern Layout: Clean, intuitive navigation
  • Fast Performance: Smooth interactions and quick loading

🔐 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
  • Security: Werkzeug password hashing
  • Frontend: HTML5, CSS3, Vanilla JavaScript
  • Design: Custom dark theme with CSS variables
  • Deployment: Docker & Docker Compose

📋 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

First Time Setup

  1. Navigate to the application URL
  2. Click "Register" to create your account
  3. Fill in username, email, and password (min 6 characters)
  4. You'll be automatically logged in
  5. Start adding your bills from the dashboard!

📊 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)

📁 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

  • FILE_UPLOADS_GUIDE.md - Complete guide to uploading and managing files
  • IMPROVEMENTS_SUMMARY.md - Recent feature additions and improvements
  • PAYMENT_HISTORY_IMPORTED.md - Payment history import details

📄 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