-BillTracker is a private, self-hosted bill planning app for households and small personal setups. It tracks recurring bills, payments, monthly cash buckets, due dates, categories, debt payoff, imports, exports, and backups from one local installation.
+BillTracker is a private, self-hosted bill planning app for households and small personal setups. It tracks recurring bills, payments, monthly cash buckets, due dates, categories, debt payoff, imports, exports, backups, transactions, bank sync, and subscriptions from one local installation.
It runs as a Node/Express app with a React/Vite frontend and stores data in SQLite. It is designed for people who want their bill data under their own control instead of inside a third-party budgeting service.
+Key features include:
+
+- SimpleFIN bank sync integration (auto-sync, manual "Sync Now", 90-day backfill)
+- Subscription catalog with recommendations from unmatched charges
+- Advisory non-bill filter system (5k+ patterns, auto-matching)
+- Transaction import, matching, and management
+- Snowball and avalanche debt payoff planning
+- Analytics, calendar, summary pages, and printable reports
+- Dark mode and PWA support (offline-ready)
+- Keyboard command palette (Ctrl+K)
+
Demo Server: https://t1.scheller.ltd/
Username: guest · Password: guest123
@@ -16,14 +27,27 @@ Username: guest · Password: guest123
## Highlights
- Private-by-design self-hosted bill tracking with local SQLite storage
-- Month-by-month tracker grouped by `1st-14th` and `15th-31st`
-- Period-aware remaining balance that switches between the 1st and 15th buckets
+- Tracker view with monthly buckets (`1st-14th` and `15th-31st`) and period-aware balance
- Bills, categories, payments, notes, skipped months, history ranges, and inactive bill handling
+- Subscription catalog (v2 with 100+ services across categories, recommendations from unmatched charges)
+- Advisory non-bill filter system (5k+ patterns, UI for confidence levels, lazy cache, auto-matching)
- Debt snowball page with payoff projections, avalanche comparison, APR math, and amortization schedules
-- Analytics, calendar, monthly summary, income, starting cash, and printable reports
-- XLSX import, import by bill, user export/import, Excel export, import history, and admin backups
-- Local username/password login with optional authentik/OIDC
-- Admin panel for users, backups, cleanup, auth settings, system status, roadmap, and migrations
+- Snowball page with detailed projections and comparison
+- Analytics, calendar, summary pages, and printable reports
+- XLSX import, CSV import, user export/import, Excel export, import history, and admin backups
+- Transaction import, matching, and management (Data page)
+- Local username/password login with optional Authentik/OIDC SSO
+- Admin panel for users, backups, cleanup, auth settings, status, and migrations
+- Status page with health checks, bank sync card, daily worker card, and recent errors
+- Compact tracker mode with side-by-side buckets, subscription/AP/2FA badges
+- Worker system (dailyWorker for autopay marking, notifications, session pruning, cleanup)
+- Dark mode and theme support
+- PWA support (service worker, offline-ready)
+- Keyboard command palette (Ctrl+K)
+- Monthly bill state (skip, notes per month), bill history and status tracking
+- SimpleFIN bank sync integration (auto-sync, manual "Sync Now", 90-day backfill, config via admin)
+- Two-factor authentication badges, autopay badges, subscription badges on bills
+- Customizable display preferences per bill (toggle columns, badges)
- Public About, Privacy, and Release Notes pages
## Screenshots
@@ -32,9 +56,23 @@ Username: guest · Password: guest123
-
+
-
+
+
+## Additional Screenshots
+
+The app includes many more screenshots in the docs:
+
+- Analytics page: spending trends, category breakdowns, heatmaps
+- Calendar page: due dates, payments, month progress
+- Summary page: income, starting amounts, monthly planning
+- Admin panel: user management, backups, status, migrations
+- Worker status: dailyWorker activity, notifications, cleanup
+- Status page: health checks, bank sync status, recent errors
+- Compact tracker mode: side-by-side buckets, subscription/AP/2FA badges
+
+See the docs directory for more details.
## Who This Is For
@@ -47,14 +85,17 @@ Good fit:
- People who split monthly cash around the 1st and 15th
- Users who want import/export and database backup control
- Authentik/OIDC users who want optional SSO
+- Users who want SimpleFIN bank sync integration
+- People managing subscriptions, debt, and transactions in one place
Not a full replacement for:
- Double-entry accounting
-- Bank syncing
- Investment tracking
- Tax software
+Note: Bank sync requires a SimpleFIN account. Direct bank connections are not supported.
+
## Quick Start With Docker
The included Compose file runs the published image on host port `3030` and stores all persistent app data under `/data` inside the container.
@@ -98,6 +139,17 @@ BACKUP_PATH=/data/backups
Back up the mounted `/data` directory like you would any other sensitive financial data.
+### Background Workers
+
+The app runs a daily worker (`dailyWorker`) for:
+
+- Autopay marking
+- Bill due notifications (3 days, 1 day, due today, overdue)
+- Session cleanup
+- Import history pruning
+
+Worker status and recent activity are visible in the Status page admin panel.
+
## Node Install
Install dependencies:
@@ -144,45 +196,112 @@ The Tracker is the main monthly view. It shows active bills for the selected mon
You can record payments, quick-pay bills, skip a bill for the month, add monthly notes, override monthly amounts, and navigate between months. The summary cards show starting cash, total paid, active period balance, overdue amount, previous month paid, and trend.
+**Compact tracker mode** (available at 2xl+ screen width) adds:
+
+- Side-by-side buckets for efficient viewing
+- Subscription/AP/2FA badges for quick identification
+- "S"/"AP"/"2FA" pill badges on bills
+- Customizable column visibility per bill
+
### Bills
Bills store the recurring source data:
- name, expected amount, due day, category
-- active/inactive state
-- billing cycle
-- autopay and 2FA markers
-- notes and account details
-- optional debt fields such as balance, APR, and minimum payment
-- inactive bill history ranges
+- active/inactive state and history visibility (default, all, ranges, none)
+- billing cycle (monthly, weekly, biweekly, quarterly, annual)
+- autopay status tracking (pending, assumed_paid, confirmed)
+- subscription detection
+- cycle type and cycle day configuration
-### Debt Snowball
+Inactive bills support history ranges for past billing periods.
+
+### Optional Debt Fields
+
+- balance, APR, and minimum payment
+- snowball ordering and exclusion flags
+- debt payoff tracking
+
+### Monthly Override State
+
+- actual_amount per month
+- is_skipped flag
+- notes per month
+
+### SimpleFIN Bank Sync
+
+SimpleFIN integration provides automated bank syncing:
+
+- Auto-sync with configurable schedule
+- Manual "Sync Now" button for immediate synchronization
+- 90-day backfill support
+- Configuration via Admin panel
+- Recommendations subsystem for unmatched bank charges
+
+### Subscription Catalog
+
+Track and manage recurring subscriptions:
+
+- v2 catalog with 100+ services across categories
+- Recommendations from unmatched bank charges
+- Category-based organization
+- Automatic subscription detection
+
+### Advisory Filter System
+
+Non-bill filtering with machine learning patterns:
+
+- 5000+ patterns for classification
+- UI for high/medium confidence filtering
+- Lazy caching for performance
+- Auto-matching from bank sync
+
+### Snowball
The Snowball page focuses on debt payoff planning:
- snowball and avalanche ordering
-- minimum-only baseline
-- live payoff projections
-- APR snapshots
+- minimum-only baseline vs. full extra payment
+- live payoff projections with APR snapshots
- amortization schedules
- drag ordering and debt exclusion
### Calendar, Summary, And Analytics
-- Calendar shows due dates, payments, and month progress.
-- Summary handles income, starting amounts, and monthly planning.
-- Analytics provides spending trends, category views, bill history, filters, heatmaps, and print output.
+- Calendar shows due dates, payments, and month progress
+- Summary handles income, starting amounts, and monthly planning
+- Analytics provides spending trends, category views, bill history, filters, heatmaps, and print output
### Data Tools
BillTracker includes:
-- XLSX spreadsheet import with preview
-- import by bill
-- user SQLite import/export
+- XLSX and CSV spreadsheet import with preview
+- Import by bill (manual entry)
+- User SQLite import/export
- Excel workbook export
-- import history
-- admin database backup, restore, download, cleanup, and retention tools
+- Transaction import, matching, and management
+- Import history with detailed stats
+- Admin database backup, restore, download, cleanup, and retention tools
+
+### Data Page
+
+The Data page manages transactions:
+
+- Import from CSV/XLSX with field mapping
+- Match transactions to bills
+- Ignore unmatched transactions
+- Transaction status tracking (matched, unmatched, ignored)
+
+### Status Page
+
+System status at a glance:
+
+- Health checks (database, SMTP, workers)
+- SimpleFIN bank sync status
+- Daily worker activity
+- Degraded state indicators
+- Recent errors list
## Privacy Model
@@ -200,7 +319,7 @@ Admins can manage users, reset passwords, configure authentication, and manage b
BillTracker supports local username/password login by default. Admins can create users, reset passwords, promote/demote users, and activate/deactivate accounts.
-Optional authentik/OIDC login can be enabled from Admin. OIDC uses authorization code flow with PKCE, state and nonce validation, and `openid-client` token validation.
+Optional Authentik/OIDC login can be enabled from Admin. OIDC uses authorization code flow with PKCE, state and nonce validation, and `openid-client` token validation.
Important behavior:
@@ -208,6 +327,7 @@ Important behavior:
- OIDC admin access requires a configured admin group.
- Local login cannot be disabled unless OIDC is configured, enabled, and mapped to an admin group.
- The default seeded admin is restricted to admin routes and cannot access personal tracker data.
+- OIDC provider name, issuer URL, client ID/secret, redirect URI, scopes, and admin group are configurable via Admin settings with environment variable fallbacks.
See [Authentik-Integration.md](docs/Authentik-Integration.md) for setup details.
@@ -239,6 +359,17 @@ CSRF_HTTP_ONLY=false
CSRF_SAME_SITE=strict
CSRF_SECURE=true
CSRF_COOKIE_NAME=bt_csrf_token
+DATA_IMPORT_ENABLED=true
+```
+
+Worker settings:
+
+```bash
+WORKER_INTERVAL_MS=86400000
+WORKER_AUTOPAY_ENABLED=true
+WORKER_NOTIFICATIONS_ENABLED=true
+WORKER_SESSION_CLEANUP_ENABLED=true
+WORKER_IMPORT_CLEANUP_ENABLED=true
```
OIDC fallback environment variables are used when matching Admin database settings are blank:
@@ -329,15 +460,41 @@ RUN_DB_MIGRATIONS=false
## Project Structure
```text
-client/ React app, pages, layout, UI components
-db/ SQLite connection, schema, startup migrations
-middleware/ auth checks, CSRF, rate limits, security headers
-routes/ Express API routes
-services/ auth, OIDC, backups, imports, cleanup, status, audit logic
-workers/ background tasks
-setup/ first-run admin setup
-scripts/ migrations, seed data, smoke/import tests
-docs/ technical references and integration guides
+bill-tracker/
+├── client/ # React app, pages, layout, UI components
+│ ├── components/ # Reusable React components
+│ │ ├── layout/ # Layout components (Sidebar, etc.)
+│ │ └── ui/ # UI components (buttons, inputs, etc.)
+│ ├── pages/ # Page components (one per route)
+│ │ ├── TrackerPage.jsx
+│ │ ├── BillsPage.jsx
+│ │ ├── CategoriesPage.jsx
+│ │ ├── CalendarPage.jsx
+│ │ ├── SummaryPage.jsx
+│ │ ├── AnalyticsPage.jsx
+│ │ ├── ProfilePage.jsx
+│ │ ├── SettingsPage.jsx
+│ │ ├── DataPage.jsx
+│ │ ├── AdminPage.jsx
+│ │ ├── LoginPage.jsx
+│ │ └── AboutPage.jsx
+│ ├── hooks/ # Custom React hooks (useAuth, etc.)
+│ ├── api.js # API client functions
+│ ├── App.jsx # React Router configuration
+│ ├── main.jsx # React entry point
+│ └── index.html # HTML template
+├── server.js # Express backend entry
+├── routes/ # API route handlers
+- services/ # Business logic layer: auth, OIDC, backups, imports, cleanup, status, audit, workers, transactions, matches, data sources, snowball, analytics, notification, export, and transaction import logic
+├── middleware/ # Express middleware
+├── db/ # Database schemas/migrations
+├── workers/ # Background job workers
+├── scripts/ # Utility scripts
+├── docs/ # Technical references and integration guides
+├── dist/ # Build output (generated)
+├── public/ # Static assets
+├── Dockerfile # Container config
+└── docker-compose.yml
```
## Documentation
@@ -345,13 +502,14 @@ docs/ technical references and integration guides
- [HISTORY.md](HISTORY.md): release history
- [CSRF-SPA-Setup.md](docs/CSRF-SPA-Setup.md): CSRF behavior for the SPA
- [Authentik-Integration.md](docs/Authentik-Integration.md): authentik/OIDC setup
+- [SimpleFIN-Integration.md](docs/SimpleFIN-Integration.md): SimpleFIN bank sync setup
- [Engineering_Reference_Manual.md](docs/Engineering_Reference_Manual.md): deeper implementation reference
## Known Limitations
-- Admin backups and user exports are not encrypted by the app.
-- Bank sync is not implemented.
-- OIDC single logout is not implemented.
+- Admin backups and user exports are not encrypted by the app. Protect downloaded files and mounted volumes yourself.
+- Bank sync via SimpleFIN is implemented, but direct bank connections are not supported (requires SimpleFIN account).
+- OIDC single logout is not implemented; users must log out from each device separately.
- Rate limiting is in-memory, so counters reset on restart and are not shared across multiple app instances.
- Multiple OIDC providers are not currently supported.
- The XLSX parser dependency has known upstream security advisories; import routes are authenticated, file-size limited, and parse spreadsheet cells as data.