VAT Billing System

Overview

The books my family's travel agency actually runs on

Every document here, whether a purchase, a sale, a return or a payment, is written as a balanced journal entry. The day book, the registers, the VAT return and the final report are all views over that one ledger, so they cannot disagree with each other. On top of that sits the part that makes it software a tax office recognises: an issued invoice is frozen the moment it is saved, the first printed copy is the original and every copy after it says so, and each sale is reported to the Inland Revenue Department as it goes out.

Double-entry from the ground up, not totals bolted onto a spreadsheet.
Three versions: 22 copied HTML pages, then a shared core, then a multi-tenant product.
Every sales invoice filed with the IRD's Central Billing Monitoring System as it is issued.
The books live on the machine and on the server at once, and the app opens with the line down.

Problem

Version one disagreed with itself

v1 was 22 standalone pages, each carrying its own copy of the navigation, the CSS and the arithmetic. A review of it recorded eight defects. Two pages calculated VAT by different formulas and reported different figures for the same money.

Two VAT engines shipping inside one product.
Reports joined on party name, so renaming a customer detached their history.
localStorage capped the business at roughly 5 MB. The real day book is 23 MB.
Importing two years of history took over seven minutes, one record at a time.

What was built

One shell over a framework-free core

I replaced the approach rather than patching the defects. About 20,000 lines of plain ES5-compatible JavaScript across 49 files, holding the whole database in memory and rendering screens by replacing HTML in one container. No view computes a balance; it asks ledger.js for figures and asks the component kit to draw them. The core modules never touch the DOM, which is the same property that lets them run headlessly under Node.

Nine voucher types over one fixed chart of accounts, and seven reports that are all sums over the same postings.
Single-writer rules: one module posts a voucher, one splits it, one persists anything, one decides what a printed copy may call itself.
Purchase, sales and both returns are one file; payments and receipts are another. They cannot drift apart because there is nothing to drift.
No build step, no bundler, no CDN. The repository is the deployment, and it runs from a USB stick.

Diagram

The VAT split

The one calculation the whole product exists to get right

An agency buys a ticket from a consolidator and sells it on. The supplier's bill is partly taxable and partly not, because the fare itself carries no VAT, and the margin has to be split along the same line when the ticket is sold. Getting it wrong does not look like a bug. It looks like a VAT return that is a few thousand rupees out, discovered months later. Both formulas live in one file and are verified against the real supplier day book, to the paisa.

The fare printed on the bill wins over reversing the VAT, because a supplier rounds VAT to two decimals, and every taxable amount within four paisa of the answer reverses to the same figure.
A sale finds its purchase by ticket number, and the profit is shared across that purchase's taxable and non-taxable parts.
A ticket with no purchase behind it calculates nothing. The three boxes open for typing and the form refuses to save until they add up to the price.
A ticket already billed warns and lets the save through, because a clerk who cannot issue the bill in front of them writes one out by hand instead.

Correctness

Invariants the ledger refuses to break

An unbalanced voucher never saves. post() sums both sides and throws if they differ by more than half a paisa, and no code path into the ledger skips that check. Totals are derived from their components rather than read off the form, and every money field is rounded to two decimals at the single write boundary, not at each of the places that might have written one.

Rounding drift is bounded and explained; the three parts always re-add to the bill.
Cancelling a voucher removes its ledger effect but keeps its number, because a tax sequence must not develop holes.
Postings and the ticket register are pure functions of the vouchers, so both are rebuilt silently rather than reported to a travel agent as damage to diagnose.
A blank box stays blank. A fare nobody filled in is not the same fact as a fare of zero.

IRD e-billing

Filing every invoice with the tax office as it is issued

A business over the turnover threshold must issue its invoices from software registered with the Inland Revenue Department and report each one to the Central Billing Monitoring System. Three rules shape the implementation: the bill is saved first and always, nothing that fails to file is ever dropped, and the browser never talks to the IRD directly.

Reporting is a consequence of issuing an invoice, not a precondition for it. A shop whose internet is down still has customers at the counter.
A failure is queued with the IRD's own reason attached and retried on a timer, on reconnect and on demand. Of the six response codes, the four that cannot be fixed by trying again are not tried again.
The taxpayer's IRD password sits in an edge function, never in a workstation's IndexedDB, and CBMS sends no CORS headers, so the call could not have left the page anyway.
The fare is filed as exempted sales rather than folded into the taxable figure, which is the whole point of the split above.

Documents

An issued invoice is final, and a reprint says so

A sales invoice and a credit note are frozen the moment they are saved. No edit, no delete, ever. That is not a stance about carefulness; it is what a tax invoice is. The buyer is holding a copy and the tax office has been told about it, so a document that can be quietly altered afterwards is not evidence of anything.

Two lawful ways to change your mind: cancel it, keeping the number and the reason in the record, or raise a credit note against it.
A purchase stays correctable, because it is the supplier's document recorded in our books rather than an invoice we issued.
The first printed copy is the tax invoice; every copy after it is marked COPY OF ORIGINAL and numbered, and emailing the PDF counts as issuing it.
Each individual copy is a row in a print log, so "who has a copy of this invoice" is a question with an answer.
The rule is enforced in the ledger so somebody is told why, and again by a database trigger so it also holds for anything reaching PostgreSQL another way.

Tickets

Making the stock visible

A ticketing agency's stock is tickets it has bought and not yet sold. That used to live implicitly in the difference between two registers, and the only way to ask what had been paid for and not billed was to read both and subtract by eye. Every passenger line on a purchase is now a row carrying the cost split it was bought at, and a sale quoting that ticket number fills in the other half.

What is unsold, oldest first, because a ticket sitting there for two months is usually not stock but an invoice somebody forgot to raise, and the screen says so.
Margin per ticket, and broken down by airline, supplier and customer.
The register is derived, and its row ids come from the purchase line rather than being generated, so two machines rebuilding it produce the same rows instead of two copies of each.
A cancelled sale releases its ticket back, enforced by a partial unique index rather than by remembering to.

Multi-tenant

One deployment, every client, separated by the database

Twelve tables, twelve row-level-security policies, and every one of them keyed to the tenant id inside the caller's signed token rather than to anything the browser can edit. PostgreSQL answers "whose books are these" on every single request, and a suspended tenant reads nothing at all.

Composite foreign keys mean a row cannot physically point across a tenant boundary.
Closed years, frozen invoices and the append-only audit log are each enforced twice: in the browser so the refusal can be explained, and in a trigger because a rule enforced only by the interface holds only until somebody opens a console.
Five ranked roles. Nobody can grant a role above their own, and the last Super Admin cannot be demoted or deleted.
Four edge functions hold every secret the browser must not: the IRD password, the mail credentials and the service key. Each of them re-checks the caller's claims server-side.

Credentials

Deleting my own password code

v3 hashed staff passwords in the browser: a salt, 12,000 rounds of SHA-256, and a check against Node's crypto implementation. It worked, and it was still the wrong place for it. Supabase Auth owns the credential now, and the migration drops the old columns instead of quietly leaving them behind.

Dropped outright: salt, password_hash, failed_attempts, locked_until.
A leaked backup should not carry credential material for logins that no longer open anything.
The app keeps only what it owns: whether a password is still temporary, and when it last changed.
Changing a password now ends the session and sends you back to sign in.

Storage

Two copies of the books, and how they stay in step

An earlier version had no replication at all, and said so in a standing warning on the Database screen: this computer holds the only copy. That was true, and it was the most serious thing wrong with the product, because a business required to keep its records for six years cannot keep them in a browser cache. Work is now written to IndexedDB first, always, and replicated to PostgreSQL in the background. Nothing anybody types waits for the network.

Push runs before pull, so the server can never overwrite an edit that had simply not uploaded yet.
Pull pages by a watermark a database trigger writes, so it is the server's clock and no disagreement between two workstations can hide a row.
The exception is a machine with no books of its own, which reads before it writes rather than posting a seeded placeholder company over a real one.
Last write wins, which is honest rather than lazy here, because the documents where a merge would matter cannot be edited at all.

Sync hardening

Teaching a failed push to fail quietly

A cycle used to send every table together, so one table refused by a policy stranded the whole queue behind it. Each table now settles on its own, and the outbox retries only what actually failed.

One refused table no longer blocks the tables queued behind it.
Rows are grouped by column shape, so a single odd row cannot fail a batch.
Fiscal years push insert-only, which is what their row-level security allows.
The exempt-column list is derived from the data rather than maintained by hand.

Performance

The migration that proved the rewrite

I pointed the rewrite at the agency's real Tally export of 29,825 rows, two years of trading, and analysed it before writing a single row. Voucher counts by type, the period covered, the parties it would create, and whether the source itself balanced.

7,445 vouchers, 1,084 parties and 8 new accounts created. 0 rows skipped.
₨845,644,371.27 of source debits posted, with the trial balance tying exactly.
Historical figures are kept as the source system had them rather than recomputed, because re-deriving a split from a rounded VAT figure moves paisa that have already been filed.
The rewrite is what made that possible: load once into memory, validate, batch the writes, flush once.

Testing

296 assertions, no test framework

The core has no DOM dependencies, so it runs headlessly under Node against a small window stand-in. There is no test framework for the same reason there is no build step: it has to keep working on a machine with nothing installed. What the seven suites check is what this system would be sued over: the arithmetic, the dates, the refusals, and what a reprint is allowed to claim to be.

Both VAT formulas against real invoices, and the gate that refuses to price a sale with no purchase behind it.
Bikram Sambat against published dates and an eighty-year round trip; the CBMS payload, its queue, and its refusal to run half-configured.
The four compliance rules: a frozen invoice, an original and its copies, a ticket finding its purchase, a repeat ticket warning and going through.
Every column the browser maps is checked to exist in schema.sql, so a rename cannot silently stop replicating.
What is not covered is stated in the README rather than left to be discovered.

Outcome

What changed for the business

The agency's books moved off spreadsheets and paper onto a system where the numbers agree by construction, a filed year cannot quietly change, and the tax office's copy of an invoice arrives at the moment the customer's does. It also made the thing sellable: there is no per-client build, so a new business is a console entry and one activation key away.

Replaced the Excel and paper bookkeeping described in the NSA Travels case study.
The statutory sales and purchase books print in the tax office's own shape, with a gap check that names any missing invoice number in plain words.
Reports export to Excel with live formulas; documents print, flatten to an image, and email as a PDF built without a PDF library.
Suspending a client is enforced by the database while their app keeps working locally.

Reflection

What building it taught me

An invariant you only document is not an invariant. Every rule that actually holds in this system holds because something refuses to proceed when it is broken, usually in more than one place. The rules I was merely careful about in v1 are the ones that broke.

Enforce constraints where they cannot be routed around, in the database rather than the form.
Compliance is a design constraint, not a feature. "The invoice cannot be edited" changes the shape of the code, not just which buttons are drawn.
Refuse rather than guess. A bill held back with a stated reason beats a filed one carrying a date the software invented.
Measure a rewrite against real data, and write down what the system does not do.

What's next

What comes next

The roadmap tracks real gaps rather than a wish list, and the two largest items on the last version of this page, Bikram Sambat handling and the IRD-format registers, have both shipped since. What is left is written down as known limits in the README first and worked on second.

Supabase Realtime, so a change lands on the other machine without waiting for the next cycle.
Per-record locking to replace last-write-wins on the records that can still be edited.
Multi-branch support inside one tenant, and foreign currency, neither of which the system does today.
Rehearsing and documenting a restore from backup, which is the most urgent item precisely because it is the least interesting.