Skip to content

Architecture

BillTracker is a single Node.js service. Express serves a built React SPA and a JSON API from the same origin.

Browser
  |
  +-- React 19 SPA (Vite, Tailwind, shadcn/ui-style primitives, TanStack Query, framer-motion)
  |
  +-- Express API
        |
        +-- route handlers
        +-- business services
        +-- background workers
        +-- SQLite through better-sqlite3

Project Layout

Path Responsibility
client/ React pages, components, hooks, API wrappers, and styles
routes/ Express request handlers
services/ Business logic, auth, sync, backups, cleanup, and status
middleware/ Auth, CSRF, rate limiting, response headers, and errors
workers/ Daily background worker
db/ SQLite schema and migration logic
scripts/ Migrations, smoke checks, setup, and deployment helpers
legacy/ Static legacy interface served at /legacy
mkdocs/ This documentation site

Startup

  1. Docker optionally runs node scripts/migrate-db.js.
  2. server.js opens the SQLite database and applies schema migrations.
  3. The server creates the first admin if bootstrap variables are present.
  4. Expired sessions are cleaned up.
  5. Express begins listening.
  6. The SimpleFIN sync worker and daily worker start.

The daily worker runs once during startup and then at 6:00 AM server-local time. It updates autopay state, sends configured reminders, prunes sessions, and runs maintenance cleanup.

Continue Reading