About the Builder

Thomas Simms — Founder & Builder of Balance On Hand

Software engineering leader building production applications with AI-assisted engineering workflows.

This page is about the engineering behind Balance On Hand. For what the product is and why it exists, see About Balance On Hand.

What I Built

Balance On Hand is a small, private budgeting application that answers one question: how much money do I actually have, now and going forward? It projects a checking balance day by day from the user's income, bills, installment loans, and buy-now-pay-later payment plans, and it runs entirely on the user's device.

  • Forward-looking balance projection across paycheck periods, a weekly projection, and a Bill Grid of scheduled obligations, all derived from the same ledger of economic events.
  • Scheduled-obligation lifecycle: bills, income sources, installment loans, and payment plans move from forecast to ledger exactly once, including midnight rollover and multi-day date-gap catch-up.
  • Offline-first progressive web app with local-only data storage and no bank connections or required account.
  • Zero-knowledge encrypted backup using the browser's Web Crypto API (AES-256-GCM) with a user-held recovery phrase, so backup storage never holds readable financial data.
  • This site: a static Firebase-hosted resource with cash-flow simulators, browser-local developer tools, consumer knowledge hubs, applied research publications, and a business portal that shares projection logic with the consumer app.

Engineering Principles

  • Reconcile, do not eyeball. Compare state before and after a change by economic-event identity, not just by rendered totals.
  • Deterministic regression tests come first. Production calculation code does not change until a failing test demonstrates the defect or analysis proves the current behavior correct.
  • Correct authority boundaries. Only the record that proves money moved (a paid or received flag set in the same pass that changes the balance) decides whether an obligation is still in the forecast. Dates alone are not authority.
  • Reload and rollover are idempotent. Rebuilding a projection, reloading the app, or crossing a day, month, or year boundary must not create, drop, or double-count an event.
  • Preserve historical state. A plan-level settlement never rewrites or deletes installments that were actually paid.

How I Work With AI

AI agents write much of the code in Balance On Hand. The engineering decisions stay human. Each defect follows the same loop:

  1. A human identifies an anomaly in a real session.
  2. An AI agent investigates and traces the state through the code.
  3. An independent AI challenges the hypothesis rather than confirming it.
  4. A failing regression test proves or disproves the defect.
  5. The fix is implemented against that test.
  6. An independent review checks the change and its blast radius.
  7. The human makes the engineering decision.

Investigation prompts are written down before any code changes, including what is known, what is only remembered, what is already covered by tests, and what would count as proof.

Selected Engineering Case Studies

Midnight rollover and projection conservation

A real session raised a concern: a remembered forward balance before midnight did not match the projection after rollover. There was no pre-midnight export, so the remembered number was treated as a reproduction clue, not as a proven before-state, and the investigation was explicitly told not to patch toward it.

Tracing the rollover path uncovered separate, real boundary defects: in the window after midnight but before the rollover sweep, an unpaid obligation due today and an unreceived paycheck due today could each be dropped from the paycheck-period cards even though the balance had not yet absorbed them. The fix made the settlement flags the single authority and added regression coverage for torn state, interrupted rollover, and the December 31 to January 1 boundary.

Paid in Full payment plans across views

An independent review of the rollover work noticed that different views could disagree about a payment plan a user had manually marked Paid in Full. The paycheck-period cards consumed the raw installment occurrences, while the Bill Grid and weekly projection consumed the active, settled-aware occurrences.

The fix aligned the cards at the existing authority boundary so every view shares one filtering rule. It deliberately did not mark future installments as individually paid: a plan-level payoff means those obligations no longer exist, which is a different fact from a historical installment that was actually paid.

Privacy and encrypted backup

Financial data lives on the user's device. Optional cloud backup is encrypted in the browser with AES-256-GCM before upload, the key is wrapped with a user-held recovery phrase, and the envelope format is versioned so older backups keep restoring. Restore, migration, deletion, and failure logging each have their own end-to-end tests.

Financial-integrity testing

The application carries hundreds of unit and end-to-end specs. The end-to-end suite freezes time, drives the real rollover path across day, month, and year boundaries, and asserts conservation: current balance changes only for events actually due or received, and every future card remains derivable from the ledger plus remaining obligations.

Technical Snapshot

  • Application: Angular, TypeScript, progressive web app with service worker, Firebase.
  • Testing: Vitest unit specs and Playwright end-to-end specs in the application; Node test runner and Playwright for this site.
  • Security: Web Crypto API, AES-256-GCM, recovery-phrase key wrapping, versioned backup envelopes.
  • This site: static HTML, CSS, and vanilla JavaScript on Firebase Hosting, with generated knowledge hubs and JSON-driven content.
  • Workflow: AI coding agents (Devin and Claude) with written investigation prompts, failing-regression-first commits, and independent review.

Background

Thomas Simms is a software engineering leader with a background in building and operating production applications. Balance On Hand grew out of a practical need to see a checking balance ahead of time for a paycheck-to-paycheck household, and it is now used as a working example of how disciplined engineering and AI-assisted development can coexist in a financial product.

Explore Balance On Hand Open App

Balance On Hand is a planning tool. It is not a bank, lender, investment platform, or financial advisor.