# EasyBill — Complete Technical Specification & Architectural Reference (`llms-full.txt`)

Product: EasyBill — Offline GST Bill & Business Book
Format: Google Chrome Extension Manifest V3
Canonical URL: https://easybill.trustoryx.digital/
Chrome Web Store: https://chromewebstore.google.com/detail/bizharvest-pro-%E2%80%94-google-b/cbajgibgeaiediocjefmbddffmlblmnk?authuser=0&hl=en-GB

---

## 1. ARCHITECTURE & ZERO-CLOUD OPERATING PRINCIPLE
EasyBill runs 100% locally on the user's computer inside Google Chrome (Manifest V3). It makes zero external HTTP/HTTPS API requests, uses zero cloud analytics, and stores all business profiles, customer master records, item catalogues, finalized bills, and payment vouchers inside local IndexedDB storage (managed through Dexie.js).

### Chrome Manifest V3 Permissions
1. `storage`: Local key-value state and extension preferences.
2. `sidePanel`: Opens the compact 360px billing workflow side-by-side with WhatsApp Web (`web.whatsapp.com`).
3. `alarms`: Wakes the extension service worker periodically while Chrome is open to check if recurring AMC / monthly bills are due.
4. `unlimitedStorage`: Grants IndexedDB quota beyond the default 50MB origin limit to safely store years of offline bills and base64 invoice logos.
5. **Prohibited Permissions (Guaranteed Zero):** No `host_permissions`, no `<all_urls>`, no `content_scripts`, no `webRequest`, no `cookies`, no `history`, and no remote code execution.

---

## 2. DETERMINISTIC INDIAN GST MATHEMATICS ENGINE
GST calculations use deterministic `Decimal.js` fixed-point arithmetic (`ROUND_HALF_UP`) to completely eliminate binary floating-point drift (e.g., `0.1 + 0.2 !== 0.3`).

### 2.1 Supply Type Detection
Let S_code = 2-digit Supplier State Code (e.g., '07' for Delhi)
Let C_code = 2-digit Place of Supply / Recipient State Code

- IF S_code === C_code:
  Supply Type = INTRA_STATE
  CGST_rate = GST_rate / 2
  SGST_rate = GST_rate / 2
  IGST_rate = 0%
- IF S_code !== C_code:
  Supply Type = INTER_STATE
  CGST_rate = 0%
  SGST_rate = 0%
  IGST_rate = GST_rate

### 2.2 Tax-Exclusive Mode ("Add GST extra on top of price")
Line Base = (Quantity * UnitPrice) - Discount
CGST_amount = round2(Line Base * (CGST_rate / 100))
SGST_amount = round2(Line Base * (SGST_rate / 100))
IGST_amount = round2(Line Base * (IGST_rate / 100))
Line Total = Line Base + CGST_amount + SGST_amount + IGST_amount

### 2.3 Tax-Inclusive Mode ("Price already includes GST")
Line Total = (Quantity * UnitPrice) - Discount
Line Base = round2(Line Total / (1 + (GST_rate / 100)))
Total Tax = Line Total - Line Base
In INTRA_STATE:
CGST_amount = round2(Total Tax / 2)
SGST_amount = Total Tax - CGST_amount  (ensures sum equals exact Total Tax with zero 1-paise discrepancy)
In INTER_STATE:
IGST_amount = Total Tax

### 2.4 Rupee Round-Off
When `roundOffToNearestRupee` is enabled:
Rounded Total = Math.round(Sum of Line Totals)
Round Off Amount = Rounded Total - (Sum of Line Totals)

---

## 3. OFFICIAL 38 INDIAN GST STATE & UNION TERRITORY CODES
01: Jammu and Kashmir
02: Himachal Pradesh
03: Punjab
04: Chandigarh
05: Uttarakhand
06: Haryana
07: Delhi
08: Rajasthan
09: Uttar Pradesh
10: Bihar
11: Sikkim
12: Arunachal Pradesh
13: Nagaland
14: Manipur
15: Mizoram
16: Tripura
17: Meghalaya
18: Assam
19: West Bengal
20: Jharkhand
21: Odisha
22: Chhattisgarh
23: Madhya Pradesh
24: Gujarat
25: Daman and Diu (Historic)
26: Dadra and Nagar Haveli and Daman and Diu
27: Maharashtra
28: Andhra Pradesh (Old)
29: Karnataka
30: Goa
31: Lakshadweep
32: Kerala
33: Tamil Nadu
34: Puducherry
35: Andaman and Nicobar Islands
36: Telangana
37: Andhra Pradesh (New)
38: Ladakh
97: Other Territory
99: Centre Jurisdiction

---

## 4. LOCAL INDEXEDDB SCHEMA (13 ACID TABLES)
1. `businesses`: Multi-tenant business profiles, legal name, GSTIN, state code, address, bank/UPI, logo data URLs, invoice prefixes.
2. `customers`: Customer name, phone, email, billing/shipping address, state code, GSTIN, notes.
3. `items`: Catalog of goods and services, HSN/SAC codes, default rate, unit of measure, default GST slab.
4. `invoices`: Saved and finalized bills, immutable snapshot of business and customer, line items, tax breakdown, status (`DRAFT`, `FINAL`, `PAID`, `PARTIAL`, `CANCELLED`).
5. `quotations`: Price estimates, scope of work, validity date, conversion link to finalized invoice.
6. `payments`: Payment records, invoice reference, payment mode (`UPI`, `BANK_TRANSFER`, `CASH`, `CHEQUE`, `CARD`), reference number, transaction date.
7. `paymentReceipts`: Official issued payment vouchers linked to payment entries.
8. `creditNotes`: Formal tax credit adjustments linked to original invoice number.
9. `debitNotes`: Formal extra debit charges linked to original invoice number.
10. `expenses`: Business operational expense records, category, amount, payment mode, vendor receipt notes.
11. `recurringSchedules`: AMC and monthly repeat billing rules, interval, next run timestamp, occurrence key.
12. `templates`: Custom visual template configurations, color palette, font stack, visible section toggles.
13. `auditLogs`: Local ledger of document modifications, payment cancellations, and backup operations.

---

## 5. CSV FORMULA INJECTION DEFENSE (CWE-1236)
When exporting CSV reports for Chartered Accountants:
Any cell string starting with `=`, `+`, `-`, `@`, `\t`, or `\r` is automatically sanitized by prefixing a single quote `'` and wrapping in RFC-4180 quotes with internal quotes escaped as `""`. This prevents malicious spreadsheet payload execution when opened in Microsoft Excel or LibreOffice Calc.