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.
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
- Sign-up creates a separate business per account. There is no email verification or password-reset email yet.
- Scanned PDFs are not read by OCR. Typed-text PDFs are imported.
- BS conversion covers the years 2000 to 2090 only.
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.