Orbit Commerce Enterprise Double-Entry General Ledger & Real-Time Financial Statements

1. Fiscal Overview & Double-Entry Accounting Core Principles

Enterprise retail platforms often suffer from a fundamental architectural flaw: decoupling operational point-of-sale activities from formal financial accounting. When retail sales, inventory movements, and supplier receipts reside in an isolated operational database while financial accounts are updated via delayed monthly batch exports, organizations encounter severe operational friction:

1. Unbalanced Out-of-Sync Ledgers: Operational registers report revenues that do not match bank deposits, while inventory valuations drift away from warehouse asset registers.
2. Delayed Executive Visibility: Chief Financial Officers and controllers must wait 15 to 30 days after month-end closure to obtain audited Profit and Loss (P&L) statements and Balance Sheets.
3. Audit Trail Vulnerabilities: Disconnected spreadsheet entries lack non-repudiable audit logs connecting general ledger balances to specific cash register slips, invoices, or dock delivery notes.
4. Retroactive Tampering: Without strict cryptographic and database-level period locks, historical transactions can be quietly altered, compromising tax compliance and financial integrity.

Orbit Commerce eliminates this divide by embedding a real-time, double-entry General Ledger directly into the persistence kernel. Every transaction executed across retail registers, warehouse docks, and credit desks immediately generates an atomic, balanced journal voucher with line-level debit and credit symmetry.

2. Chart of Accounts (COA) Architectural Hierarchy

The Chart of Accounts defines the financial taxonomy of the enterprise. Orbit Commerce organizes accounts into five standard classifications, enforcing normal balance rules and financial statement mapping:

Codebase Anchors & Grounded Architecture

The General Ledger and accounting subsystem is implemented across the modular backend application server and relational persistence kernel:

• Client General Ledger Console: Interactive double-entry ledger interface, journal voucher inspection, and Trial Balance reporting desk (accounting-view.tsx at apps/commerce/src/components/pos/accounting-view.tsx).
• Backend Accounting Engine: General ledger transaction service (commerce-accounting.service.ts at apps/api/src/modules/commerce/services/commerce-accounting.service.ts), providing assertBalanced, assertFiscalPeriodNotLocked, and automated event posting routines (postSaleJournalEntry, postReturnJournalEntry, postKhataPaymentEntry, postGoodsReceiptEntry, postStockTakeAdjustmentEntry).
• Relational Persistence Schema & Migrations: Core database migration 027_phase8_labels_promos_ledger_zreports.sql (packages/db/migrations/027_phase8_labels_promos_ledger_zreports.sql) establishing accounts, journal_entries, and journal_lines tables with atomic balance constraints and row-level tenant security boundaries.

3. General Ledger Journal Console User Interface

The General Ledger Journal Console provides accounting teams and financial controllers with real-time audit tools, manual journal entry creation, and ledger balance inspection.

4. Visual Double-Entry Capital Flow Schematic

Capital moves through the commercial operating environment across three distinct phases: Customer Tender Ingress, Clearing Transit, and Balance Sheet Settlement.

5. Automated Operational Posting Events & Voucher Templates

Orbit Commerce maps domain operations to balanced double-entry vouchers automatically. The core operational posting methods execute within database transactions, rigorously verifying assertBalanced to guarantee that total debits match total credits before committing:

1. Sale Journal Voucher (postSaleJournalEntry)

Fired upon completion of retail or commercial sales checkouts:

Voucher: JV-SALE-2026-08149
Event Action: COMMERCE_SALE_POSTED
Reference: Invoice #INV-2026-08149

Account Code | Account Title                         | Debit (Dr)  | Credit (Cr)
-------------|---------------------------------------|-------------|------------
1010         | Cash on Hand (Cash Tender)            | $   65.00   | -
1020         | Bank / Card Clearing (Card Tender)    | $  120.00   | -
1050         | Accounts Receivable (Khata Credit)    | $   35.00   | -
4020         | Sales Discounts & Promos              | $   10.00   | -
2020         | Output VAT Payable (15%)              | -           | $   28.70
4010         | Gross Sales Revenue                   | -           | $  201.30
--------------------------------------------------------------------------------
5010         | Cost of Goods Sold (Perpetual COGS)   | $  112.50   | -
1200         | Merchandise Inventory (Asset Deplete) | -           | $  112.50
--------------------------------------------------------------------------------
TOTALS       | Balanced Multi-Leg Sale Journal Entry | $  342.50   | $  342.50

2. Merchandise Return Voucher (postReturnJournalEntry)

Fired when a customer returns goods for a refund:

Voucher: JV-RET-2026-00214
Event Action: COMMERCE_RETURN_POSTED
Reference: Return #RET-2026-00214

Account Code | Account Title                         | Debit (Dr)  | Credit (Cr)
-------------|---------------------------------------|-------------|------------
4030         | Sales Returns & Refunds               | $   50.00   | -
2020         | Output VAT Payable (Tax Reversal 15%) | $    7.50   | -
1010         | Cash on Hand (Cash Refund Tender)     | -           | $   57.50
--------------------------------------------------------------------------------
1200         | Merchandise Inventory (Restocked)     | $   28.00   | -
5010         | Cost of Goods Sold (COGS Reversal)    | -           | $   28.00
--------------------------------------------------------------------------------
TOTALS       | Balanced Return Journal Voucher       | $   85.50   | $   85.50

3. Customer Debt Khata Settlement (postKhataPaymentEntry)

Fired when an on-account credit customer pays off aging balance:

Voucher: JV-KHT-2026-00812
Event Action: COMMERCE_KHATA_PAYMENT_POSTED
Reference: Payment #PAY-8812

Account Code | Account Title                         | Debit (Dr)  | Credit (Cr)
-------------|---------------------------------------|-------------|------------
1010         | Cash on Hand (or 1020 Bank Deposit)   | $  850.00   | -
1050         | Accounts Receivable (Customer Khata)  | -           | $  850.00
--------------------------------------------------------------------------------
TOTALS       | Balanced Debt Settlement Voucher      | $  850.00   | $  850.00

4. Dock Goods Receipt Capitalization (postGoodsReceiptEntry)

Fired when warehouse dock inspectors finalize intake for a vendor purchase order:

Voucher: JV-GRN-2026-00481
Event Action: COMMERCE_GOODS_RECEIPT_POSTED
Reference: Dock Intake PO-2026-00481

Account Code | Account Title                         | Debit (Dr)  | Credit (Cr)
-------------|---------------------------------------|-------------|------------
1200         | Merchandise Inventory Asset           | $ 4,722.00  | -
2010         | Accounts Payable / GRNI Clearing      | -           | $ 4,722.00
--------------------------------------------------------------------------------
TOTALS       | Balanced Dock Intake Goods Receipt    | $ 4,722.00  | $ 4,722.00

5. Stock Take Discrepancy Reconciliation (postStockTakeAdjustmentEntry)

Fired when physical inventory count audits identify discrepancies against the system book balance:

Voucher: JV-STK-2026-08420
Event Action: COMMERCE_STOCK_AUDIT_POSTED
Reference: Stock Take Reconciliation #ST-2026-0842

Account Code | Account Title                         | Debit (Dr)  | Credit (Cr)
-------------|---------------------------------------|-------------|------------
5020         | Inventory Shrinkage & Waste Expense   | $   184.50  | -
1200         | Merchandise Inventory Asset           | -           | $   184.50
--------------------------------------------------------------------------------
TOTALS       | Balanced Stock Adjustment Voucher     | $   184.50  | $   184.50

6. Financial Periods, Lock Governance & Year-End Rollover

A critical feature of enterprise general ledgers is the ability to lock historical periods. In dynamic retail environments, backdated invoices or inventory adjustments accidentally posted into previously reported months disrupt quarterly tax filings and audited financial statements.

Period Lock Assertion Mechanism

Orbit Commerce implements a strict chronological lock guard:

1. State Inspection: Whenever a user or operational process submits a journal entry, the system invokes assertFiscalPeriodNotLocked(entryDate, tenantId).
2. Audit State Resolution: The engine retrieves the latest audit log stamped with action FISCAL_PERIOD_LOCKED.
3. Threshold Gate: If entryDate <= lockedBeforeDate, the request is immediately rejected: "Cannot post or backdate entries into a locked fiscal period (Period locked on or before 2026-09-30)"
4. Audit Trail Immutability: Locking or unlocking a period emits FISCAL_PERIOD_LOCKED or FISCAL_PERIOD_UNLOCKED audit events with actor ID, timestamp, and formal justification.

Year-End Profit Rollover to Retained Earnings

At the conclusion of the fiscal year, controllers execute the year-end closing routine. The engine aggregates all Revenue and Expense accounts, calculates Net Operating Profit, and posts a closing entry that zeroes out temporary P&L accounts into Retained Earnings (Account 3010):

Voucher: JV-YEAREND-2026
Event Action: COMMERCE_FISCAL_YEAR_CLOSED
Description: Annual Income Summary Rollover to Retained Earnings

Account Code | Account Title                         | Debit (Dr)   | Credit (Cr)
-------------|---------------------------------------|--------------|------------
4010         | Gross Sales Revenue (Zeroed Out)      | $1,840,000.00| -
4020         | Sales Discounts (Zeroed Out)          | -            | $  34,000.00
4030         | Sales Returns (Zeroed Out)            | -            | $  22,000.00
5010         | Cost of Goods Sold (Zeroed Out)       | -            | $1,050,000.00
5020         | Inventory Shrinkage (Zeroed Out)      | -            | $  18,500.00
5050         | Cash Over / Short (Zeroed Out)        | -            | $   1,500.00
3010         | Retained Earnings (Net Profit Credit) | -            | $ 714,000.00
--------------------------------------------------------------------------------
TOTALS       | Balanced Year-End Closing Entry       | $1,840,000.00| $1,840,000.00

7. Deviation Handling & Exception Protocols

Accounting teams must follow standardized remediation procedures when encountering ledger variances:

8. High-Frequency Triage & Accounting FAQs

How does Orbit Commerce handle multi-currency accounting when branches operate across borders?

Transactions maintain both original transaction currency amounts and functional base currency equivalents locked at the transaction exchange rate. While line items display local tender currency (e.g., AED or EUR), every General Ledger journal line records amounts in the primary functional currency (e.g., USD or SAR). Realized exchange rate variances occurring between order booking and settlement are automatically posted to Realized FX Gain/Loss (Account 5810).

Can an operator delete or overwrite an existing posted journal entry?

No. Posted journal entries are strictly immutable and cannot be deleted or directly modified under any circumstances. In accordance with GAAP and IFRS auditing standards, any necessary accounting correction must be executed through a new reversing journal entry (Credit what was Debited, Debit what was Credited) referencing the original voucher identifier.

How quickly does the Trial Balance reflect a retail sale made at a cashier terminal?

The Trial Balance updates instantaneously within the same millisecond the cashier transaction commits. Because operational sales trigger inline synchronous calls to postSaleJournalEntry, the journal entry and lines are written within the same database transaction boundary. Opening the Trial Balance report immediately reflects the updated numbers.

9. Related Operations & Lateral Internal Links

Maintain end-to-end operational mastery across cashiering, inventory, and procurement:

• Review cashier shift closures and till balancing: Register Shifts, Cashier Blind Drops & Day Closure Z-Reports.
• Explore dock receiving and asset capitalization: Vendor Purchase Orders & Docked Goods Receiving Inspections.
• Examine customer credit ledgers: Customer Khata Debt Ledgers & Aging Settlement Desk.
• Master inventory audits and write-downs: Physical Stock Take Broadsheet & FEFO Reconciliation.
• Multi-location warehouse transfers: Inter-Store Stock Transfers & In-Transit Custody Tracking.