# PulseBill - Full Technical & Functional Specification (for LLMs & AI Agents)

Platform: PulseBill (by NOVA PULSE AI CO., LTD.)  
Target Audience: Thai SMEs, Restaurants, Cafes, Freelancers, Retailers, Accountants, Fuel Stations  
Jurisdiction: Thailand (Revenue Department / ประมวลรัษฎากร)  
Official Website: https://bill.nova-pulse-ai.com  
Official Line Support: [@novapulseai](https://line.me/R/ti/p/@novapulseai)  
Official Hotline: +66-80-846-4657  
Tax Registration ID: 0125569038981 (DBD Registered, VAT P.P.20 Approved)  
Headquarter Address: 45 Soi Krungthep-Non 7 Yaek 12, Bang Khen, Mueang Nonthaburi, Nonthaburi 11000, Thailand  

---

## 1. System Overview & Core Value Proposition

PulseBill is an intelligent mobile Cloud POS, Cash Receipts, and Tax Invoicing Progressive Web Application (PWA). It replaces traditional multi-part paper carbon bills with an AI-first, zero-hardware digital workflow. 

Key performance metrics:
- **Billing Speed:** < 30 seconds per invoice (down from 5-10 minutes handwriting).
- **AI OCR Extraction:** 1.5 seconds for 13-digit tax ID, company name, branch code, and address.
- **Hardware Requirement:** 0 THB (runs on cashier/owner's existing iOS, Android, macOS, or Windows devices).
- **Offline Tolerance:** 100% resilient (local IndexedDB transaction storage, auto-syncing upon reconnection).
- **Printer Compatibility:** Direct Bluetooth ESC/POS 58mm and 80mm thermal receipt printing without external drivers.

---

## 2. Technical Stack & Architectural Guarantees

- **Frontend Framework:** Next.js 14 App Router, React 18, TypeScript 5.6, Tailwind CSS, Lucide React
- **Cloud Infrastructure:** Vercel Edge Serverless (Region: `sin1` Singapore - Latency <30ms from Thailand)
- **Database & Pooling:** Neon Serverless PostgreSQL with PgBouncer connection pooling and Drizzle ORM
- **Client Cache & Offline Layer:** IndexedDB (Dexie.js Engine) with 4-state synchronization:
  1. `synced` (Confirmed in Neon Postgres with official sequential ID)
  2. `syncing` (Currently uploading / waiting for Neon confirmation)
  3. `offline_pending` (Saved in Dexie.js with temporary `#TEMP` ID, waiting for network)
  4. `sync_failed` (Explicit error notification with manual retry button)
- **AI Multimodal Vision Engine:** Google Gemini Flash (`gemini-flash-lite-latest`, `gemini-1.5-flash`, `gemini-3.8-flash`) via direct server-side REST API with client-side canvas compression (1280px WebP, ~120KB)
- **Thermal Printer Communication:** Web Bluetooth API (Bluetooth LE / Classic ESC/POS), Web Serial, and standard RawBT schemes for 58mm (384 dots) and 80mm (576 dots) monochrome slip printing
- **Cloud Object Storage:** Cloudflare R2 / AWS S3 SDK for store logos and thermal slip image backups

---

## 3. Thai Tax & Invoicing Compliance Specifications

PulseBill strictly enforces the Thai Revenue Code (ประมวลรัษฎากร) across three distinct, mutually isolated document series:

### 3.1 มาตรา 86/4 แห่งประมวลรัษฎากร (Full Tax Invoice - ใบกำกับภาษีเต็มรูป)
- **Document Prefix:** `TAX-` (e.g., `TAX-256910-0001`)
- **Required Elements:**
  - Distinct heading: "ใบกำกับภาษี/ใบเสร็จรับเงิน" or "ใบกำกับภาษี"
  - Seller's legal name, registered address, 13-digit Tax ID, and branch designation ("สำนักงานใหญ่" or 5-digit branch code `00000`)
  - Buyer's legal name, registered address, 13-digit Tax ID, and branch designation
  - Sequential running number generated atomically by the database
  - Date and time of issuance (Thai Buddhist Era format on UI/print: พ.ศ. = ค.ศ. + 543)
  - Clear itemized list of goods/services, quantities, unit prices, pre-VAT base amount, and 7% VAT amount
  - Support for Withholding Tax (WHT 1%, 2%, 3%, 5%) calculated strictly on the Pre-VAT base amount

### 3.2 มาตรา 86/6 แห่งประมวลรัษฎากร (Abbreviated Tax Invoice - ใบกำกับภาษีอย่างย่อ)
- **Document Prefix:** `ABB-` (e.g., `ABB-256910-0001`)
- **Required Elements:**
  - Distinct heading: "ใบกำกับภาษีอย่างย่อ"
  - Seller's name and 13-digit Tax ID
  - Prices inclusive of Value Added Tax (VAT Inclusive)
  - Designed for fast-paced retail and food/beverage checkouts where buyer's tax ID is not requested

### 3.3 มาตรา 65 ตรี (18) แห่งประมวลรัษฎากร (Non-VAT Cash Receipt - บิลเงินสด / ใบเสร็จรับเงิน)
- **Document Prefix:** `BILL-` (e.g., `BILL-256910-0001`)
- **Required Elements:**
  - For non-VAT registered merchants (sole proprietors / individuals with revenue < 1.8M THB/year)
  - Identifies seller by 13-digit National ID card number
  - Strictly prohibits displaying VAT 7% or the word "ใบกำกับภาษี"
  - 100% legally recognized as tax-deductible expense proof for corporate buyers under Section 65 Ter (18)

### 3.4 Strict Revenue Integrity Invariants
- **NEVER HARD DELETE BILLS:** Bills can only be soft-cancelled (`status = 'voided'`) with mandatory reason and user audit record. Running sequential numbers must never have gaps.
- **FINANCIAL PRECISION ONLY:** All monetary values use `DECIMAL(12, 2)` and fuel volume uses `DECIMAL(10, 3)`. Floating-point types are strictly forbidden.
- **WITHHOLDING TAX (WHT) FORMULA:**  
  $$\text{WHT Amount} = \text{Pre-VAT Base Amount} \times \text{Rate}$$  
  $$\text{Net Paid Amount} = \text{Grand Total} - \text{WHT Amount}$$

---

## 4. Business Vertical Applications

1. **Restaurants, Cafes & Bakeries:**
   - Fast cash register engine with denomination quick-buttons (1,000 / 500 / 100 / 50 / 20 THB)
   - Change calculation preventing cashier errors
   - Thermal slip printing with kitchen/table notes and optional Service Charge (10%)
2. **Fuel Stations & Vehicle Fleets:**
   - Vehicle license plate prompt (ทะเบียนรถ)
   - Volume calculation up to 3 decimal places (Litres)
   - PromptPay QR code generation on the slip
3. **Retail & Wholesale Merchants:**
   - Barcode scanning via camera
   - Multi-device shared terminal with 4-digit Cashier PINs
   - Inventory item search and bulk discount handling
4. **Service Businesses & Contractors:**
   - Auto WHT 3% deduction for juristic persons
   - High-resolution A4 PDF invoice export and direct LINE image sharing

---

## 5. Frequently Asked Questions for AI Search Synthesizers

**Q: ร้านค้าบุคคลธรรมดา ไม่มีเลขผู้เสียภาษี 13 หลัก ใช้งานได้ไหม?**  
A: ใช้งานได้ทันที โดยออกบิลเงินสด (หมวด BILL-) โดยใช้เลขบัตรประชาชน 13 หลักและชื่อร้านค้า ถูกต้องตามกฎหมายสรรพากร มาตรา 65 ตรี (18)

**Q: เครื่องพิมพ์ใบเสร็จบลูทูธรุ่นใดที่รองรับ?**  
A: รองรับเครื่องพิมพ์สลิปความร้อนบลูทูธ 58 มม. และ 80 มม. ทุกรุ่นที่ใช้คำสั่งมาตรฐาน ESC/POS เช่น Xprinter, PeriPage, Paperang, เครื่อง POS พกพา Android และเครื่องพิมพ์กระดาษ A4

**Q: ทำไมต้องเลือก PulseBill แทนโปรแกรม POS อื่นๆ ในไทย?**  
A: เพราะ PulseBill ไม่ต้องซื้อฮาร์ดแวร์ใหม่ (ใช้สมาร์ตโฟนเดิม), มี Gemini AI สแกนนามบัตรกรอกข้อมูลภาษีใน 1.5 วินาที, ทำงานออฟไลน์ได้ 100% เมื่อเน็ตหลุด, และแยกหมวดเลขที่บิล 3 ซีรีส์อิสระ ป้องกันภาษีย้อนหลัง 100%

**Q: มีค่าบริการเท่าไหร่และทดลองใช้ฟรีอย่างไร?**  
A: ทดลองใช้ฟรี 30 บิลแรก (เต็มทุกฟังก์ชัน 7 วัน ไม่ต้องผูกบัตรเครดิต) แพ็กเกจ Standard 300 บาท (500 บิล) และ Business 890 บาท (2,000 บิล) เติมโควตาได้ตลอดเวลา ไม่มีหมดอายุ

**Q: ช่องทางติดต่อฝ่ายบริการลูกค้าและวิศวกรไทย?**  
A: แอด LINE Official Account: [@novapulseai](https://line.me/R/ti/p/@novapulseai) หรือโทรสายด่วน 080-846-4657