← All articles

Production app · PostgreSQL

I replaced my uncle’s paper billpad with software

By Kushal Sapkota (LinkedIn) · Panauti, Nepal ·

I’m Kushal Sapkota, a Django developer and AI-automation engineer from Panauti, Nepal. Many small shops here still keep their accounts on a paper billpad: date, bill number, debit, credit, and a balance worked out by hand. One wrong subtraction in the middle quietly spoils every balance after it. I built KusBill to replace that, starting from the same columns so people can adopt it without relearning anything.

The source is on GitHub. It is built with Next.js, TypeScript, PostgreSQL, Prisma and Zod, and it has 148 automated tests that run against a real PostgreSQL database.

148automated tests
0stored balance columns
2calendars (BS and AD)

Decision 1: never store the balance

The obvious design adds a balance column and updates it on every write. It breaks the moment someone edits an old entry, because every later row is now wrong, and you have two numbers that can disagree.

KusBill stores only the entries. The balance is computed when the page is read, with a SQL window function over the ordered history (date, then entry sequence). This is the shape of the real query, simplified:

opening_balance
  + SUM(CASE WHEN status = 'POSTED'
             THEN (debit - credit) * sign ELSE 0 END)
    OVER (ORDER BY transaction_date, seq
          ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)
  AS balance

Editing, inserting, reversing or deleting an old entry changes every later balance automatically, because there is no second copy to keep in step. The sign comes from a setting: the billpad-compatible default is Previous + Debit − Credit, and a shop can switch to the opposite convention. The rule in force is printed on every ledger and report.

The trade-off is documented in the project: reading balances this way is comfortably fast for tens of thousands of entries. For millions of rows, a materialised running balance would be the next step.

Decision 2: the opening balance is its own record

The balance brought forward from the paper pad is a separate record tied to a financial year, not a fake first transaction. Balances carry forward across months and years and never reset at a calendar boundary.

Decision 3: serialise writers per business

Two people entering bills at once can interleave and produce confusing results. Writes run in a transaction that first takes a per-business PostgreSQL advisory lock (pg_advisory_xact_lock). One business’s writers queue up in order, while other businesses are never blocked.

Decision 4: two calendars

Entries can be typed in Bikram Sambat (BS) or Gregorian (AD). The conversion is tested for every BS month from 2000 to 2090, including year boundaries and leap years. Dates outside that range are rejected for BS entry, and AD entry always works.

What the tests cover

Debit and credit entry, running balances, the opening balance and carry-forward, edits to old entries, duplicate warnings, double-submit protection, concurrent writers, daily, monthly and annual totals, tenant isolation between businesses, import validation, and PDF, Excel and CSV export.

Honest limitations

If you build something for a shop near you, start from their existing paper habits, not from your idea of a better system.

Keep reading

How I built a WhatsApp ordering agent in n8n. All articles are on the articles page. You can also see the KusBill case study, or find me on GitHub and LinkedIn.