Order-to-Cash & GST Compliance Engine

Case Study: Order-to-Cash & GST Compliance Engine

Executive Summary

This case study covers the order-to-cash and tax-compliance layer of a custom ERP built for an artisan D2C brand selling across retail, B2B job-work, and consignment channels. The engine unifies four invoice types (retail, B2B, consignment sale, consignment settlement) behind one typed pipeline: state resolution → tax split → gapless sequencing → receivables ledger → automated settlement. Every rule below is enforced in code, not in operator discipline.

The Business Challenge

Indian GST filing punishes small numerical inconsistencies. Splitting a total tax of ₹0.25 into CGST and SGST by rounding each half independently yields ₹0.13 + ₹0.13 = ₹0.26 — one paisa of drift that fails GSTR-1 reconciliation at filing time. CGST Rule 46 requires consecutive, gapless invoice numbering, so a counter that increments outside the write transaction leaves a permanent gap whenever a save fails. And with three sales channels producing documents concurrently, spreadsheet-based settlement meant nobody could answer "what is outstanding, per partner, right now."

System Architecture

The engine is a set of cooperating invariants inside the ERP's Next.js App Router backend (118 API routes, Mongoose 9 on MongoDB Atlas):

1. State Resolution: Orders derive customerState automatically from the 6-digit shipping pincode in a pre-save hook, deciding intra-state (CGST/SGST) versus inter-state (IGST) treatment without manual entry.
2. Tax Split Service: A single splitGstHalves(totalTax) helper allocates the remainder paisa to one half, preserving cgst + sgst === totalTax on every odd-paise amount. Grand totals are computed as taxable + cgst + sgst + igst — the identity only holds after the split.
3. Gapless Sequence Service: generateSequenceNumber() hard-rejects any call without a MongoDB ClientSession when the prefix is GST-critical (INV, CINV, CSINV, CN, DN), making the counter bump atomic with the document write.
4. Receivables Ledger: receivableAmount, amountReceived, balanceOutstanding, paymentStatus, and embedded receipts[] live directly on the Invoice model — receivables derive from grandTotal for sale invoices and netReceivable for consignment settlements.
5. Settlement Automation: A daily server cron generates the previous month's vendor consignment settlements during the first 3 UTC days of a new month; the operation is idempotent, and manual generation remains as the recovery path.

[Order Intake] ──(pincode → state)──> [Tax Split] ──(ClientSession)──> [Gapless Sequence]
                                                                            │
[Settlement Cron] <──(monthly, idempotent)── [Receivables Ledger] <─────────┘

Key Engineering Decisions

• Paise-preserving GST splits: Intra-state invoices must call splitGstHalves — never independent round(total/2) twice. This one rule is the difference between clean and failed GSTR-1 reconciliation on odd-paise amounts.
• Transactional sequence numbers: CGST Rule 46 demands gapless numbering. Sequence generation for the five GST-critical prefixes refuses to run outside a transaction, so a failed caller can never burn a number.
• Optimistic Concurrency Control on financial models: Invoices, credit notes, debit notes, and vendor ledgers carry Mongoose's optimisticConcurrency versioning — a stale concurrent edit fails with a VersionError instead of silently overwriting money data.
• Vendor bill cross-validation: Cumulative vendor bills against a purchase order are capped at 110% of the PO amount, blocking accidental double-billing at the API boundary.
• Job-work audit trail: B2B job-work orders record the buyer's inward delivery challan reference, preserving the Section 143 audit trail for customer-supplied materials.

Database Schema & Optimization

Receivable state is derived, never duplicated: a single helper module is the source of truth for receivable amount, paid/partial/unpaid state, last receipt date, and intra/inter-state inference. Month-close runs three reconciliation checks — inventory consistency, vendor ledger consistency, and invoice-order reconciliation — and refuses to close a month whose ledgers disagree.

Results & Retrospective

• All five GST document prefixes issue gaplessly under concurrent load — sequence numbers are minted inside the same transaction as the document.
• GSTR-1 reconciliation drift from tax-split rounding is structurally ₹0.00: the invariant is enforced by the only code path that can split a tax amount.
• The brand's 5,313-row product catalog export reconciles against invoiced line items across all four invoice types.
• Consignment partners are settled automatically each month; the spreadsheet workflow is gone, and outstanding balances are queryable per partner in real time.