KB-212 – Accounting Engine Architecture¶

Knowledge Base ID: KB-212
Chapter: 6 - Account Resolution Engine
Project: BLACK ERP
Version: 0.6
Status: Draft
Last Updated: 2026-06-26
Applies To: ADempiere 3.9.4

Purpose¶

This chapter explains how ADempiere determines which General Ledger account should be used when creating accounting entries.

Before a FactLine can be created, the Accounting Engine must resolve a valid accounting combination (C_ValidCombination) that represents the destination account for the accounting movement.

This process is known as the Account Resolution Engine.

Understanding this mechanism is essential for every accounting customization.

Why Account Resolution Exists¶

Business documents never contain General Ledger accounts.

For example:

A Purchase Invoice contains:

Vendor
Product
Tax
Charge
Organization
Warehouse

None of these objects stores the debit or credit account directly inside the posting process.

Instead, the Accounting Engine must determine:

Which accounting account corresponds to this business object?

High-Level Flow¶

Business Document
        │
        ▼
Doc_*
        │
        ▼
getAccount(...)
        │
        ▼
Account Resolution
        │
        ▼
C_ValidCombination
        │
        ▼
FactLine
        │
        ▼
FACT_ACCT

The FactLine never invents accounts.

It always receives an already resolved account combination.

The getAccount() Concept¶

Most Doc_* implementations eventually call helper methods inherited from the Doc base class.

Conceptually:

Account account =
    getAccount(AccountType, as);

Where:

AccountType identifies which business account is required.
as represents the Accounting Schema.

The returned object already contains the accounting combination required to create the FactLine.

Sources of Accounting Accounts¶

Depending on the business object, the account may originate from different locations.

Typical examples include:

Business Object	Source
Product	Product Accounting
Business Partner	Customer/Vendor Accounting
Tax	Tax Accounting
Charge	Charge Accounting
Bank Account	Bank Accounting
Cash Book	Cash Accounting
Project	Project Accounting
Warehouse	Warehouse Defaults
Accounting Schema	Default Accounts

The Accounting Engine knows where to search according to the requested account type.

Account Resolution Hierarchy¶

Conceptually, ADempiere searches for accounting information using a hierarchy.

Business Object
        │
        ▼
Accounting Configuration
        │
        ▼
Accounting Schema
        │
        ▼
Account Combination
        │
        ▼
FactLine

Different business objects expose their accounting configuration differently, but the overall resolution process remains consistent.

Valid Account Combination¶

The Accounting Engine does not work directly with individual GL accounts.

Instead, it uses:

C_ValidCombination

A valid combination contains much more than the natural account.

Typical dimensions include:

Account
Organization
Product
Business Partner
Project
Campaign
Activity
User Elements

Therefore, every FactLine references a complete accounting combination rather than only an account number.

Example¶

Suppose a Vendor Invoice is posted.

The posting logic needs the Vendor Liability account.

Conceptually:

Vendor Invoice

↓

Business Partner

↓

Vendor Accounting

↓

201.001.001

↓

C_ValidCombination

↓

Credit FactLine

The posting class never hardcodes account 201.001.001.

It retrieves the configured accounting combination from the accounting metadata.

BLACK ERP Example¶

During the Mexican VAT Cash Basis implementation, the Allocation posting logic required resolving four additional accounts:

119.001 — VAT Pending Payment
118.001 — VAT Paid
209.001 — VAT Collected Pending
208.001 — VAT Collected

Rather than hardcoding these accounts, the implementation resolves their corresponding C_ValidCombination records before creating the accounting entries.

This approach preserves compatibility with future accounting configuration changes.

Engineering Principles¶

The Accounting Engine follows several important principles.

Business logic never hardcodes GL accounts.
Every account must be resolved through accounting metadata.
FactLine objects always receive valid account combinations.
Accounting customization should extend the resolution process rather than bypass it.

These principles ensure flexibility across organizations, accounting schemas and localizations.

Key Takeaways¶

Business documents do not contain accounting accounts.
Doc resolves accounts before creating FactLine objects.
Different business objects expose different accounting configurations.
C_ValidCombination is the central accounting reference.
Account resolution is one of the most critical services provided by the Accounting Engine.

Next Chapter¶

Chapter 7 explores the internal structure of MAcctSchema, MAccount, C_ValidCombination, and the accounting metadata used during account resolution.

Revision History¶

Version	Date	Description
0.6	2026-06-26	Added Account Resolution Engine architecture.