Orbit Universal Double-Entry General Ledger & Multi-Vertical Chart of Accounts Specification

1. Accounting Topology & System Architecture

The core accounting engine is defined in database migration 027_phase8_labels_promos_ledger_zreports.sql and orchestrated by apps/api/src/modules/commerce/services/commerce-accounting.service.ts. It provides an enterprise double-entry accounting foundation that records the financial impact of every physical transaction:

[Operational Transaction Ingress]
 (Sales, Returns, Reagent Dosing, Faculty Payroll, Fee Challans)
                 |
                 v
  [Universal Accounting Service Engine]
  - Resolves Chart of Accounts Head (accounts table)
  - Constructs Balanced Journal Voucher (journal_entries table)
  - Synthesizes Line-Item Debits & Credits (journal_lines table)
                 |
                 v
   [Mathematical Balance Invariant Gate]
   Invariant: sum(journal_lines.debit) === sum(journal_lines.credit)
                 |
       +---------+---------+
       |                   |
   [BALANCED]          [UNBALANCED]
       |                   |
 [Post to Ledger]     [Reject: SQL Invariant Error]

2. Interactive General Ledger Journal Console

Financial controllers, bursars, and chief accountants audit real-time general ledger postings, inspect T-accounts, and verify day-end closing vouchers via the central financial console:

3. Relational Schema & Mathematical Invariant Design

The database schema models double-entry accounting through four primary relational tables:

3.1 Relational Models

1. accounts: Master Chart of Accounts hierarchy storing account codes, descriptive titles, account classification types (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE), and active statuses.
2. journal_entries: Header records containing unique sequential entry numbers (entryNo), operational source references (referenceType, referenceId), human audit descriptions, posting timestamps, and authorizing user IDs.
3. journal_lines: Individual transaction legs recording the target accountId, debit amount, credit amount, and memo notes.
4. z_reports: Cashier register day-end summaries linking fiscal date totals directly to their generated journalEntryId.

3.2 Mathematical Balance Invariant

Every posted journal entry must satisfy the fundamental double-entry invariant:

$$\sum_^ \texti \equiv \sum^ \text_i$$

At the application service level, postJournalEntry() calculates the absolute discrepancy:

const totalDebit = lines.reduce((acc, line) => acc + Number(line.debit || 0), 0);
const totalCredit = lines.reduce((acc, line) => acc + Number(line.credit || 0), 0);

if (Math.abs(totalDebit - totalCredit) > 0.001) {
  throw new BadRequestException(
    `Mathematical balance invariant violation: Debits (${totalDebit}) must equal Credits (${totalCredit})`,
  );
}

Any attempt to commit an unbalanced transaction immediately rolls back the database transaction, preventing orphaned or asymmetrical entries.

4. Universal Chart of Accounts (COA) Taxonomy

The Orbit Chart of Accounts uses a standardized 5-tier classification structure shared across all industry verticals:

4.1 Master Account Directory Table

5. Day-End Z-Report Auditing & Automated Voucher Posting

At the conclusion of each operating shift or business day, cashiers print a Z-Report to reconcile physical cash drawers with system sales records.

5.1 Shift Reconciliation Workflow

1. Blind Count Ingress: The cashier inputs counted physical currency denominations (e.g., 5000, 1000, 500, 100 PKR notes) without previewing system expected totals.
2. Supervisor Discrepancy Approval: If variance exceeds approved tolerance thresholds (such as $\pm 500\text$ ), a supervisor authorization PIN is mandated.
3. Automated Journal Voucher Generation: The system creates a balanced day-end journal voucher in journal_entries and updates z_reports.journalEntryId:

Debit:  GL 1020 (Cash in Till)                 = Actual Counted Cash
Debit:  GL 1010 (Bank Clearing)               = Total Electronic Payments
Debit:  GL 5090 (Cash Shortage Expense)        = Variance (if short)
Credit: GL 5095 (Cash Overage Income)          = Variance (if over)
Credit: GL 4010 (Gross Sales Revenue)         = Net Sales Total
Credit: GL 2110 (Output Tax Payable)          = Collected Sales Tax

The Z-Report status advances to POSTED, locking the business day against retroactive cashier modifications.

6. Financial Engine Throughput & Reconciliation Telemetry

The general ledger engine delivers fast posting throughput:

7. Failure Modes & Recovery SOP

The following operational contingency protocols resolve financial accounting exceptions:

8. Cross-Vertical Internal Linkages

The universal General Ledger links financial operations across all product modules:

• Double-Entry General Ledger & Financial Periods in Retail — Integrates retail POS inventory and vendor purchase order accounting.
• Recipe Yield, WAC Costing & Realtime Depletion — Translates restaurant ingredient depletion into food cost expense vouchers.
• Doctor Portal Referrals & Commission Settlement — Posts clinical referral commissions to Accounts Payable liabilities.
• Faculty Monthly Payroll & Currency-in-Words Payslips — Balances academic payroll disbursements against operational bank accounts.
• Enterprise SQL Kernel Row-Level Security — Guarantees complete tenant privacy across multi-tenant ledger accounts.