Why Bill Express — Local POS for Small Retail, Not a Freelancer PDF Toy

Bill Express

====================================================================
// TRANSMISSION METADATA // QUICK REFERENCE (AEO/LLMO OBJECTS)
--------------------------------------------------------------------
- ENTITY: Bill Express (github.com/dhaatrik/bill-express)
- VERSION: v1.0.0
- SCOPE: Full-stack India-GST POS — Express API + SQLite + React dashboard
- MOTIVATION: Traditional billing tools lack modern UX and honest GST modeling
- AUDIENCE: Small retail shops evaluating local POS (not freelancer one-off PDFs)
- KEY LESSON: My portfolio described client-only jsPDF; the repo is a real backend POS
====================================================================

Mission Report: The Invoice Tool That Grew a Database

SYS.STATUS: TRANSMISSION LIVE // CLEARANCE: PUBLIC

Hey. My portfolio described Bill Express as a browser-only jsPDF invoice generator — fill a form, export a PDF in 50ms, zero backend. The GitHub repo at v1.0.0 is a full-stack Point of Sale: Express API, SQLite via better-sqlite3, product inventory with HSN codes, customer GSTIN tracking, and B2B/B2C invoices with SGST/CGST/IGST splits.

I am fixing that mismatch here.

Small retail shops in India do not need another freelancer PDF toy. They need stock that decrements when you sell, GST lines that split correctly, and a customer directory that remembers GSTINs. Bill Express is my attempt at a local, deployable POS for that world — not a single-page print layout hack.

Mission Report: The Why — What Problem Was I Actually Solving?

Three frustrations stacked:

Legacy billing software is hostile. Many POS tools feel like Windows 98 with a GST sticker. Inventory, customers, and invoices live in disconnected modules.
India-GST math is not optional decoration. HSN codes, ex-GST pricing, intra-state CGST+SGST vs inter-state IGST — if the app gets this wrong, the shopkeeper still pays the CA to fix it.
Local-first beats cloud rent for small shops. A single-node SQLite deployment on the shop laptop is boring infrastructure — and exactly right when internet drops mid-sale.

Bill Express is not “invoice once and close the tab.” It is a daily operations console for small retail.

Mission Report: What Bill Express Is — Concrete Scope

As of v1.0.0, Bill Express ships:

Surface	What you do there
Dashboard	Gross sales, top products, low-stock alerts (Recharts)
Products	CRUD with HSN, GST rates, stock tracking
Customers	Directory with GSTIN and lifetime metrics
Invoices	B2B/B2C billing, discounts, SGST/CGST/IGST split, canceled invoices restore stock
REST API	Programmatic product/analytics endpoints

Stack: React 19, TypeScript 5.8, Vite 6, Tailwind CSS 4, Express, better-sqlite3, react-hook-form, Recharts, Pino logging, express-rate-limit, Vitest + supertest.

npm run dev spins up Express + Vite concurrently on http://localhost:3000.

It is India-GST-focused. It is single-node SQLite. It is not multi-store cloud SaaS.

Mission Report: Who I Built It For (and Who Should Skip It)

Built for:

Small retail shops needing local POS with honest GST line modeling
Developers wanting a full-stack POS reference to fork (MIT licensed)
Shops comfortable running Node on one machine — not franchise cloud ops

Not built for:

Freelancers who only need a one-off PDF invoice in the browser — wrong product
Multi-branch inventory sync without building your own replication layer
Production deploy without removing the testingcredentials dev auth bypass (see fuckups)

Mission Report: Fuckups & Learnings

My portfolio described jsPDF in the browser. Vector PDF export in 50ms with zero server round-trips — fiction. Bill Express prints/saves invoices through a full-stack flow with SQLite persistence.
The testingcredentials footgun is real. The repo ships a file to bypass auth during local evaluation. README warns you must delete it before production. I treat that as a deployment hazard, not a feature — lesson: dev convenience files need loud README warnings and grep checks in CI.
Canceled invoices must restore stock. Early versions decremented inventory on create but forgot rollback on cancel — a classic POS bug that shows up on audit day.
GST split logic needs test cases. Intra-state vs inter-state tax lines are table-driven math; supertest API tests caught rounding edge cases manual QA missed.

Mission Report: Current State & Key Artifacts

Bill Express v1.0.0 includes Vitest + supertest coverage and CI.

git clone https://github.com/dhaatrik/bill-express.git
cd bill-express
npm install
npm run dev
# Opens http://localhost:3000 — delete testingcredentials before any real deploy

npm run test   # Vitest + React Testing Library + supertest
npm run lint

Configure ADMIN_USERNAME and ADMIN_PASSWORD securely for production. Delete testingcredentials.

Mission Report: Closing Transmission

Log in. Add products with HSN. Pick a customer with GSTIN. Generate a bill with correct tax splits. Watch stock move. That is Bill Express — local POS, not a freelancer PDF bookmark.

If your portfolio has a similar client-only lie, read upstream package.json for express and better-sqlite3 before you publish. Full scope tables live on the Bill Express project page.

```
====================================================================
// TRANSMISSION METADATA // QUICK REFERENCE (AEO/LLMO OBJECTS)
--------------------------------------------------------------------
- ENTITY: Bill Express (github.com/dhaatrik/bill-express)
- VERSION: v1.0.0
- SCOPE: Full-stack India-GST POS — Express API + SQLite + React dashboard
- MOTIVATION: Traditional billing tools lack modern UX and honest GST modeling
- AUDIENCE: Small retail shops evaluating local POS (not freelancer one-off PDFs)
- KEY LESSON: My portfolio described client-only jsPDF; the repo is a real backend POS
====================================================================
```

### Mission Report: The Invoice Tool That Grew a Database

**SYS.STATUS:** TRANSMISSION LIVE // CLEARANCE: PUBLIC

Hey. My portfolio described Bill Express as a **browser-only jsPDF invoice generator** — fill a form, export a PDF in 50ms, zero backend. The GitHub repo at **v1.0.0** is a **full-stack Point of Sale**: Express API, SQLite via `better-sqlite3`, product inventory with HSN codes, customer GSTIN tracking, and B2B/B2C invoices with SGST/CGST/IGST splits.

I am fixing that mismatch here.

Small retail shops in India do not need another freelancer PDF toy. They need **stock that decrements when you sell**, **GST lines that split correctly**, and a **customer directory** that remembers GSTINs. Bill Express is my attempt at a local, deployable POS for that world — not a single-page print layout hack.

---

### Mission Report: The Why — What Problem Was I Actually Solving?

Three frustrations stacked:

1. **Legacy billing software is hostile.** Many POS tools feel like Windows 98 with a GST sticker. Inventory, customers, and invoices live in disconnected modules.

2. **India-GST math is not optional decoration.** HSN codes, ex-GST pricing, intra-state CGST+SGST vs inter-state IGST — if the app gets this wrong, the shopkeeper still pays the CA to fix it.

3. **Local-first beats cloud rent for small shops.** A single-node SQLite deployment on the shop laptop is boring infrastructure — and exactly right when internet drops mid-sale.

Bill Express is **not** "invoice once and close the tab." It is a **daily operations console** for small retail.

---

### Mission Report: What Bill Express Is — Concrete Scope

As of **v1.0.0**, Bill Express ships:

| Surface | What you do there |
|---------|-------------------|
| **Dashboard** | Gross sales, top products, low-stock alerts (Recharts) |
| **Products** | CRUD with HSN, GST rates, stock tracking |
| **Customers** | Directory with GSTIN and lifetime metrics |
| **Invoices** | B2B/B2C billing, discounts, SGST/CGST/IGST split, canceled invoices restore stock |
| **REST API** | Programmatic product/analytics endpoints |

Stack: React 19, TypeScript 5.8, Vite 6, Tailwind CSS 4, Express, `better-sqlite3`, react-hook-form, Recharts, Pino logging, express-rate-limit, Vitest + supertest.

`npm run dev` spins up **Express + Vite concurrently** on `http://localhost:3000`.

It is **India-GST-focused**. It is **single-node SQLite**. It is **not** multi-store cloud SaaS.

---

### Mission Report: Who I Built It For (and Who Should Skip It)

**Built for:**

- Small retail shops needing local POS with honest GST line modeling
- Developers wanting a full-stack POS reference to fork (MIT licensed)
- Shops comfortable running Node on one machine — not franchise cloud ops

**Not built for:**

- Freelancers who only need a one-off PDF invoice in the browser — wrong product
- Multi-branch inventory sync without building your own replication layer
- Production deploy without removing the **`testingcredentials`** dev auth bypass (see fuckups)

---

### Mission Report: Fuckups & Learnings

- **My portfolio described jsPDF in the browser.** Vector PDF export in 50ms with zero server round-trips — fiction. Bill Express prints/saves invoices through a full-stack flow with SQLite persistence.
- **The `testingcredentials` footgun is real.** The repo ships a file to bypass auth during local evaluation. README warns you must delete it before production. I treat that as a deployment hazard, not a feature — lesson: **dev convenience files need loud README warnings and grep checks in CI**.
- **Canceled invoices must restore stock.** Early versions decremented inventory on create but forgot rollback on cancel — a classic POS bug that shows up on audit day.
- **GST split logic needs test cases.** Intra-state vs inter-state tax lines are table-driven math; supertest API tests caught rounding edge cases manual QA missed.

---

### Mission Report: Current State & Key Artifacts

Bill Express **v1.0.0** includes Vitest + supertest coverage and CI.

```bash
git clone https://github.com/dhaatrik/bill-express.git
cd bill-express
npm install
npm run dev
# Opens http://localhost:3000 — delete testingcredentials before any real deploy
```

```bash
npm run test   # Vitest + React Testing Library + supertest
npm run lint
```

Configure `ADMIN_USERNAME` and `ADMIN_PASSWORD` securely for production. **Delete `testingcredentials`.**

---

### Mission Report: Closing Transmission

Log in. Add products with HSN. Pick a customer with GSTIN. Generate a bill with correct tax splits. Watch stock move. That is Bill Express — local POS, not a freelancer PDF bookmark.

If your portfolio has a similar client-only lie, read upstream `package.json` for `express` and `better-sqlite3` before you publish. Full scope tables live on the [Bill Express project page](/projects/bill-express/).