Centralized Ledger Engine Simulator Manual

Contents

1. Opening balance and ledger health
2. Guided walkthrough and rule labels
3. Wallet model
4. Action reference
5. Posting controls
6. Business and branch scope
7. Documents versus ledger truth
8. Reconciliation
9. Toasts and micro-interactions
10. Known simplifications
11. Behaviour correction log
12. Open design questions
13. Acceptance tests

Guided Walkthrough And Rule Labels

Start Guided Walkthrough teaches the documented behavior step by step without automatically resetting current state. Reviewers can click the highlighted control in Financial Actions, or use Next: Run This Action to perform the same action and continue.

Run Full Simulation resets and executes the complete scenario immediately. It is useful for inspecting the final data shape, but it is not a guided explanation.

Each walkthrough step offers Business, Accounting, and Engineering perspectives and compares expected outcomes with live simulator state.

Use Reset and Restart for a deterministic walkthrough. Use Exit Walkthrough to keep the resulting state and inspect it manually.

Opening Balance And Ledger Health

The simulator starts with a GH₵200,000 Built wallet balance. It creates a real opening ledger transaction rather than inserting a display-only number:

Dr Built E-Payment Wallet       GH₵200,000
Cr Opening Balance Equity       GH₵200,000

Immediately after reset there is one transaction and two entries. The equal totals demonstrate that the opening position is balanced.

Opening Balance Equity is a simplified demonstration counterpart. The real rebuild needs an approved migration policy defining retained earnings, owner capital, prior-period balances, or a controlled migration clearing account.

Wallet Model

Current code evidence shows an operational wallet balance, wallet credit/debit transactions, balance-before/balance-after snapshots, available-balance calculations, and links from wallet transactions to ledger rows.

The proposed design keeps two related views:

• Operational wallet: current balance, available balance, pending transfers, channels, and provider references.
• Accounting wallet control account: immutable general-ledger entries representing wallet receipts and payments.

Wallet receipt:
Dr Built E-Payment Wallet
Cr Counterpart Account

Wallet payment:
Dr Expense / Payable / Other Counterpart
Cr Built E-Payment Wallet

The operational wallet should reconcile to the ledger control account. Timing differences should be explained through pending or settlement-clearing accounts.

Action Reference

Posting Engine Controls

1. Require business and branch scope.
2. Validate accounts and posting permissions.
3. Require equal debit and credit totals.
4. Reject insufficient wallet payments.
5. Reject duplicate idempotency keys.
6. Persist the transaction and all entries atomically.
7. Correct posted history through reversal rather than deletion.

A production implementation should use integer minor units or fixed-precision decimals for money.

Business And Branch Scope

business_id: BUS-SME-001
branch_id: BR-ACCRA

The simulator carries this scope on financial events, transactions, and entries. Entry-level branch dimensions support shared costs and cross-branch allocations, but the team must confirm whether that flexibility is required.

Operational Documents Versus Ledger Truth

Quotes, invoices, bills, sales, payments, journals, imports, and wallet payments explain business intent. The ledger records the accounting effect. Mutable document balances may be cached, but they must be reproducible from ledger and settlement records.

Reconciliation

Reconciliation creates a separate match object and does not modify ledger values. This permits partial, split, one-to-many, and reversible matches with actor and timestamp history.

Toasts And Micro-Interactions

Toasts report successful postings, blocked actions, reversals, reconciliation, duplicate events, and insufficient funds. The persistent What Changed strip names the latest transition and lists exact account deltas. New transactions and documents enter with short motion cues, affected account rows are highlighted, and wallet movement displays a positive or negative delta. Reduced-motion preferences are respected.

Open the Posting Engine Schema Explorer for proposed tables, fields, constraints, legacy mappings, and migration controls.

Known Simplifications

The current simulator simplifies FX, taxes, fees, partial payments, holds, settlement delays, refunds, chargebacks, credit notes, prepayments, payroll, withholding, approvals, period locks, permissions, cross-branch allocation, and inventory valuation. Each needs explicit posting recipes and tests before implementation.

Behaviour Correction Log

Open Design Questions

1. What legally and operationally does the Built wallet represent?
2. At which provider state does an e-payment become accounting cash?
3. Are processing fees gross-posted or netted from settlement?
4. Can one transaction allocate across branches?
5. How are pending balances and settlement timing differences represented?
6. What reversal rules apply to transfers, failures, refunds, and chargebacks?
7. Which edits are allowed before posting and which require reversal?

Recommended Acceptance Tests

• Quotes create no ledger entries.
• Invoice issue balances without changing wallet cash.
• E-payment increases wallet exactly once.
• Duplicate provider events are idempotently rejected.
• Wallet payments decrease the wallet and reject insufficient funds atomically.
• POS postings correctly handle revenue, tax, COGS, inventory, and tender account.
• Reversals restore wallet balance without deleting history.
• Paid-invoice amendments reverse settlement before replacement.
• Reconciliation does not alter ledger amounts.
• Reports can be rebuilt from ledger entries.

The Markdown version contains additional implementation notes and should remain the primary editable source.