Bill Tracker

A modern, containerized web application for tracking recurring bills, utilities, subscriptions, and insurances with email reminders and calendar arithmetic.

Features

• Multi-user with Role Isolation:
  • The first registered user automatically becomes the administrator.
  • Strict privacy: users can only see their own bills; admins cannot view other users' bills directly.
  • Alphanumeric usernames up to 48 characters, passwords up to 1024 characters.
  • Passwords hashed securely with Argon2.
  • Two-Factor Authentication (2FA): Time-based One-Time Passwords (TOTP) with scannable QR code generated offline.
• Flexible Bill Tracking:
  • Track rent, utilities, internet, online subscriptions, car insurances, etc.
  • Details: name, description, integer amount, payment method, payment link, recurrence.
  • Smart Calendar Arithmetic: Recur monthly, every n months, or every n days. Month-end dates (e.g. January 31st) are clamped automatically to the last day of subsequent months (February 28th/29th) without losing original recurrence target days.
  • Early Payments & Mark as Paid: Mark payments as paid early or on time. Next due date advances, reminders are suppressed, and an explicit payment log is maintained so accidentally clicked payments can be undone with one click.
• Automated Email Reminders:
  • Dedicated background scheduler worker loop service in docker-compose.yml.
  • Configurable multiple reminder thresholds per bill (e.g. on due date, 1 day before, 7 days before, 14 days before, or custom N days).
  • Strict idempotency: database unique constraints guarantee no reminder is ever sent twice.
• Complete Audit Trail:
  • Stores all site events (who did what) in the database indefinitely.
  • Every sent email is recorded in the audit log.
  • Viewable and searchable by administrators directly in the web UI.
• In-App Site Configuration:
  • Configure SMTP host, port, credentials, security (TLS/SSL/none), application base URL, currency (default: CZK), and source link directly in the Admin UI.
  • Configuration persists in config.json inside the mounted data volume.
  • Includes SMTP test email utility.
• Clean UI & Modern Design:
  • Vanilla JavaScript frontend with zero JavaScript dependencies.
  • Responsive layout: desktop navbar collapsing to a mobile hamburger menu on narrow screens.
  • Dark mode and Light mode with instant theme detection and persistence.
  • Social media and link preview HTML meta tags on every page.
  • Favicon served at /favicon.ico.
  • Footer stating "vibe-coded with gemini flash" with a link to source code.

Persistence & Volume Architecture

A single volume ./data is mounted to /app/data in the container.

What Persists in ./data:

1. app.db - SQLite database storing users, bills, payment logs, sent reminders, and audit logs.
2. config.json - In-app system configuration (SMTP settings, app URL, currency, source code URL).
3. secret_key - Flask secret key, generated atomically using secrets.token_bytes(32) on initial deployment.

Everything else in the container is ephemeral and stateless.

Getting Started with Docker Compose

Prerequisites

• Docker (with Docker Compose v2)

Running the Application

1. Start the web app and dedicated reminder scheduler:

   docker compose up -d --build
   

2. Access the application in your browser:

   http://localhost:5000
   

   (Or custom port via PORT=5002 docker compose up -d)

3. Register the first account to become the administrator.

4. Go to Site Settings (/admin/settings) to configure your SMTP settings and application URL.