8. Accounting & Common Entries

The Accounting & Common Entries module is the foundation of NkapBooks' financial system. Every financial transaction — whether a sales invoice, purchase payment, or manual journal entry — ultimately flows through the double-entry accounting engine and creates balanced ledger entries. This section covers the core accounting infrastructure shared across all other modules.

8.1 Double-Entry Accounting

Every financial transaction in NkapBooks creates balanced ledger entries following the fundamental accounting equation:

Assets = Liabilities + Equity + (Income − Expenses)

Core Principles

Debit and Credit Rules

The Transactional Model

NkapBooks uses a Transactional base class for all documents that create accounting entries. Documents that extend Transactional include:

Ledger Posting

The LedgerPosting class handles the creation of AccountingLedgerEntry records:

1. The document's getPosting() method builds a list of debit and credit entries.
2. On submit, the posting creates AccountingLedgerEntry rows in the database.
3. On cancel, the posting creates reversal entries (debits become credits and vice versa) and marks original entries as reverted.

8.2 Chart of Accounts

The Chart of Accounts is a hierarchical tree of all financial accounts in your organisation. It is the backbone of the accounting system — every ledger entry references an account from this tree.

Schema Overview

Root Types

Every account belongs to exactly one root type, which determines its fundamental behavior:

Account Types

Account types provide additional classification for system-level behavior. The following types are available:

Tree Structure

The Chart of Accounts is rendered as a tree view in the NkapBooks interface:

Company Name (Root Label)
├── Assets
│   ├── Current Assets (Group)
│   │   ├── Cash In Hand
│   │   ├── Bank Account
│   │   ├── Accounts Receivable (Debtors)
│   │   └── Inventory
│   └── Fixed Assets (Group)
│       ├── Equipment
│       └── Accumulated Depreciation
├── Liabilities
│   ├── Current Liabilities (Group)
│   │   ├── Accounts Payable (Creditors)
│   │   └── Tax Payable
│   └── Long Term Liabilities (Group)
│       └── Loans
├── Equity
│   ├── Capital
│   └── Retained Earnings
├── Income
│   ├── Sales Revenue
│   └── Service Income
└── Expenses
    ├── Cost of Goods Sold
    ├── Rent
    ├── Utilities
    └── Salaries

Key Rules

Country-Specific Templates

NkapBooks ships with pre-built Chart of Accounts templates for many countries. During the Setup Wizard, the appropriate template is loaded based on your selected country. This includes:

• SYSCOHADA (OHADA countries): Cameroon, Senegal, Ivory Coast, Mali, Gabon, etc. — uses the standardised French-language accounting structure with numbered accounts (e.g., 411-Clients, 401-Fournisseurs, 571-Caisse).
• India: Template with GSTIN-compatible account structure.
• Switzerland: Regional accounting settings.
• International: A generic English-language template for other countries.

Managing Accounts

• Add: Click the "+" button in the tree view. Set the account name, select a parent, and choose whether it's a group.
• Edit: Click on an account to open the Quick Edit panel. Account name can be changed; root type, parent, and account type are read-only after creation.
• Archive: Set archived: true to hide the account from dropdowns while preserving historical data.

8.3 Journal Entries

Journal Entries are manual ledger entries for transactions not covered by standard invoices or payments. They are the most flexible accounting tool in NkapBooks.

Schema Overview

Entry Types

Account Entries (Child Table)

Each row in the Account Entries table represents one side of the double-entry:

Auto-Balancing

The JournalEntryAccount model includes auto-balance formulas:

• When you enter a debit amount in one row and move to the next, the system automatically calculates the credit amount needed to balance the entry (and vice versa).
• This works across multiple rows — the system calculates the difference between total debits and total credits and fills in the missing value.

Journal Entry Lifecycle

Draft  →  Submitted  →  Cancelled

Submitting a Journal Entry

When a Journal Entry is submitted:

1. The getPosting() method iterates over all account rows.
2. For each row with a non-zero debit, a debit AccountingLedgerEntry is created.
3. For each row with a non-zero credit, a credit AccountingLedgerEntry is created.
4. The posting validates that total debits equal total credits.

Common Use Cases

Actions

8.4 Accounting Ledger Entries

Accounting Ledger Entries are the atomic records of the double-entry system. They are never created manually — they are generated automatically when submittable documents (invoices, payments, journal entries) are submitted.

Schema Overview

How Entries Are Created

Reversal Mechanism

When a document is cancelled:

1. Each original ledger entry is marked as reverted: true.
2. A new reversal entry is created with:
   • Debit ↔ Credit swapped (original debit becomes credit, original credit becomes debit)
   • reverted: true
   • reverts pointing to the original entry
3. The net effect is zero — the original and reversal entries cancel each other out.

Viewing Ledger Entries

Ledger entries are viewable through:

• General Ledger Report — filter by account, party, date range, or reference document.
• Account Balances — shown inline in the Chart of Accounts tree.
• Ledger Link Action — available on submittable documents (invoices, payments, journal entries).

List View Columns

8.5 Party Management

Parties are the universal record for customers and suppliers in NkapBooks. A single Party record can serve as a customer, supplier, or both.

Schema Overview

Role-Based Behavior

SYSCOHADA Account Defaults

For businesses in OHADA member countries, default accounts are automatically set:

Outstanding Amount Calculation

The outstandingAmount field is automatically recalculated and represents the net amount owed:

This calculation uses optimistic concurrency control with retry logic (up to 3 retries) to handle concurrent updates safely.

Loyalty Points Calculation

For customers with a loyalty program, loyaltyPoints is calculated by summing all LoyaltyPointEntry records where the expiry date has not passed. Points are recalculated automatically when invoices are submitted.

Party Actions

The Party form provides context-sensitive action buttons:

Duplication

When duplicating a Party, the outstandingAmount and loyaltyPoints are reset to zero — these are calculated values that should start fresh for a new record.

List View Columns

8.6 Tax Templates

Tax Templates define reusable tax configurations that can be applied to invoices. Each template can contain multiple tax detail rows for compound taxes.

Tax Template Schema

Tax Detail Schema (Child Table)

Each tax detail row defines a single tax component:

How Tax Templates Work

1. On Invoices: When a tax template is applied to a Sales or Purchase Invoice, the system:
   • Calculates the tax amount for each item based on the rate.
   • Creates a TaxSummary row showing the total tax per account.
   • Adds the tax to the Grand Total.
2. On Payments: When a payment is created against a taxed invoice, the system:
   • Uses the Tax Payment Account (if set) for the payment's tax ledger entries.
   • If no payment account is specified, falls back to the invoice account.

Compound Taxes

You can create compound tax templates with multiple rows. For example:

Both rows are applied independently, resulting in an effective rate of 18%.

Archiving

Tax templates can be archived (archived: true) to hide them from dropdowns while preserving historical references on existing documents.

8.7 Payment Methods

Payment Methods define the accepted forms of payment for your business and link them to the appropriate GL accounts.

Schema Overview

Default Payment Method Types

Where Payment Methods Are Used

Account Auto-Fill Logic

When a payment method is selected on a Payment document:

1. The system loads the PaymentMethod document.
2. If the method type is Cash, the POS counter's cash account is used (for POS payments).
3. For Bank and Mobile Money, the method's linked account is used.
4. For non-Cash methods, additional fields appear:
   • Reference ID — External reference number
   • Clearance Date — Expected clearing date

Archiving

Payment methods can be archived to hide them from selection dropdowns while maintaining references on historical documents.

List View Columns

8.8 Number Series

Number Series controls the automatic document numbering for all major document types in NkapBooks. Each series defines a prefix, starting number, and zero-padding configuration.

Schema Overview

Default Number Series

How Numbering Works

1. When a new document is created, the system finds the Number Series matching the document's numberSeries field and referenceType.
2. The current counter is incremented by 1.
3. The new document number is generated: {prefix}{padded current}.
4. With padZeros: 4 and current: 42, the result is SINV-0042.

Customisation

You can customise number series by:

Example: Custom Numbering

8.9 Multi-Currency

NkapBooks supports transactions in multiple currencies, with automatic exchange rate handling and gain/loss accounting.

Currency Schema

NkapBooks ships with a pre-loaded list of world currencies that is available immediately after setup.

How Multi-Currency Works

System Currency

The system currency is set during the Setup Wizard and is stored in SystemSettings.currency. All reports and summaries are denominated in this currency.

Party Currency

Each Party (customer/supplier) can have a default currency set on their record. When a transaction is created for that party, the system uses the party's currency by default.

Exchange Rate on Transactions

When a transaction is created in a foreign currency:

1. The invoice or payment shows an Exchange Rate field.
2. The exchange rate converts foreign currency amounts to the system currency.
3. All GL entries are posted in the system currency using the exchange rate.

Exchange Gain/Loss

When a payment is made at a different exchange rate than the original invoice:

• Exchange Gain: If the payment settles for less in system currency → recorded as income.
• Exchange Loss: If the payment settles for more in system currency → recorded as expense.

These entries are created automatically by the Payment document's posting logic.

Currency in Practice

Archiving Currencies

Currencies can be archived to hide them from dropdowns while preserving references on historical transactions. This is useful for cleaning up the currency list if many unused currencies are loaded by default.

8.10 Accounting Settings

Accounting Settings is a singleton document that controls company-wide accounting configuration and feature toggles.

Schema Overview

Account Settings

Feature Toggles

These checkboxes enable or disable optional features across the application:

Fiscal Year

The fiscal year dates are used by financial reports (Profit & Loss, Balance Sheet, Trial Balance) to determine the reporting period.

Feature Dependency Chain

Some features depend on others:

Enable Pricing Rule  →  Enable Coupon Code
                     (Coupon Code is hidden until Pricing Rule is enabled)

Regional Settings

Setup Complete Flag

The setupComplete flag (hidden) is set to true after the Setup Wizard completes. This flag:

• Makes the parentAccount field required on new Account records.
• Indicates that the Chart of Accounts has been initialised.
• Prevents re-running certain setup operations.

Best Practices

Chart of Accounts

1. Don't over-complicate — Start with the pre-built template for your country and only add accounts as needed.
2. Use groups — Organise accounts into logical groups for cleaner reports.
3. Archive, don't delete — When an account is no longer needed, archive it instead of deleting it.
4. Keep account names descriptive — Use clear names that anyone can understand (e.g., "Office Rent" instead of "Account 623").

Journal Entries

1. Use the right entry type — Always select the most appropriate entry type for audit clarity.
2. Add references — Include reference numbers and user remarks on every journal entry.
3. Attach documentation — Upload supporting documents (receipts, approvals) as attachments.
4. Review before submitting — Journal entries cannot be edited after submission — only cancelled.

Party Management

1. Choose roles carefully — Set the role to Customer or Supplier if the party serves only one purpose. Use Both only when the same entity is both a customer and a supplier.
2. Set default accounts — For SYSCOHADA countries, ensure default accounts are correctly mapped.
3. Keep contact info current — Email and phone are used for communication and POS item enquiry auto-fill.

Tax Templates

1. Create one template per tax regime — e.g., "VAT 19.25%", "VAT 0% (Exempt)".
2. Set both invoice and payment accounts — If your tax authority requires different accounts for collected vs. paid tax.
3. Test with a sample invoice — Before using a new tax template in production, create a test invoice to verify the calculations.

Number Series

1. Use meaningful prefixes — Choose prefixes that clearly identify the document type.
2. Plan before starting — Changing number series mid-year can cause confusion. Plan your numbering strategy before going live.
3. Use sufficient padding — Set padZeros high enough to accommodate growth (4–6 digits is typical).

Accounting Impact Summary

How Documents Create Ledger Entries

The Audit Trail

Every financial transaction in NkapBooks creates an unbroken audit trail:

1. Source Document — The invoice, payment, or journal entry that initiated the transaction.
2. Accounting Ledger Entries — Individual debit/credit records linked back to the source document.
3. General Ledger Report — A chronological view of all entries per account.
4. Trial Balance — Summary of all account balances to verify the books are balanced.
5. Financial Statements — Profit & Loss and Balance Sheet derived from the ledger.