KB-212 – Accounting Engine Architecture¶
Knowledge Base ID: KB-212
Chapter: 11 - Posting Lifecycle & Transaction Management
Project: BLACK ERP
Version: 1.1
Status: Draft
Last Updated: 2026-06-26
Applies To: ADempiere 3.9.4
Purpose¶
This chapter explains what happens after a document-specific accounting implementation finishes building its accounting entries.
Previous chapters described how createFacts() generates Fact and FactLine objects.
This chapter explains how those accounting objects are validated, balanced, persisted and committed as a single transactional unit.
Understanding this lifecycle is essential for developing reliable accounting customizations.
Where We Are in the Posting Process¶
At the end of Chapter 10 the accounting implementation has already executed:
createFacts(MAcctSchema as)
The result is:
Fact[]
↓
Fact
↓
FactLines
At this stage nothing has yet been written into the database.
Everything still exists only in memory.
High-Level Posting Lifecycle¶
Once createFacts() returns, the Posting Engine continues with the following sequence.
createFacts()
↓
Fact[]
↓
Validate Facts
↓
Validate Accounts
↓
Validate Balance
↓
Persist FactLines
↓
Commit Transaction
↓
Posting Complete
Every posted document follows this lifecycle regardless of its business type.
In-Memory Construction¶
One of the most important architectural decisions in ADempiere is that accounting entries are fully constructed before any database update occurs.
Conceptually:
Fact
↓
FactLine
↓
Validation
↓
Persistence
This guarantees that incomplete accounting entries are never partially stored.
Validation Phase¶
Before persistence begins, the Accounting Engine validates every generated accounting document.
Typical validations include:
- Accounting schema exists
- Posting period is open
- Valid account combinations
- Active accounts
- Postable accounts
- Balanced debit and credit totals
- Currency consistency
If any validation fails, posting immediately stops.
Balance Verification¶
Every Fact must satisfy the fundamental accounting equation.
Total Debit
=
Total Credit
Conceptually:
Fact
↓
Σ Debit
↓
Σ Credit
↓
Balanced?
Only balanced accounting documents continue to persistence.
Transaction Management¶
Posting executes inside a database transaction.
Conceptually:
BEGIN TRANSACTION
↓
Persist FactLines
↓
Persist Accounting Metadata
↓
Commit
or
Rollback
This guarantees atomicity.
Either every accounting entry is stored successfully or none of them are.
Persistence Phase¶
Once validation succeeds, each FactLine is written into:
FACT_ACCT
Conceptually:
Fact
↓
FactLine
↓
INSERT FACT_ACCT
Every accounting movement becomes an individual General Ledger record.
Commit¶
If every insert succeeds:
Commit
The accounting document becomes permanently available for:
- Financial Reports
- Trial Balance
- General Ledger
- Account Inquiry
- Period Closing
Rollback¶
If any error occurs during posting:
Rollback
The database returns to its previous consistent state.
No partial accounting remains.
Typical causes include:
- Invalid account
- Closed accounting period
- Currency inconsistency
- Database constraint violation
- Runtime exception
Error Recovery¶
Conceptually:
Validation Error
↓
Rollback
↓
Posting Status = Error
↓
Business Document remains unchanged
The user may correct the underlying problem and attempt posting again.
BLACK ERP Example¶
During the Mexican VAT Cash Basis implementation, additional VAT reclassification entries are generated before persistence.
Conceptually:
Doc_AllocationHdr
↓
createFacts()
↓
Standard FactLines
+
VAT FactLines
↓
Validation
↓
Commit
↓
FACT_ACCT
If any of the VAT accounts cannot be resolved, the entire posting transaction is rolled back.
No partial VAT accounting is stored.
This behavior preserves accounting integrity without requiring custom transaction management.
ACID Properties¶
The posting process naturally follows the ACID principles of transactional databases.
| Property | Meaning |
|---|---|
| Atomicity | Posting succeeds completely or not at all |
| Consistency | Accounting rules remain valid |
| Isolation | Concurrent postings remain independent |
| Durability | Committed entries survive system failures |
These properties are inherited from the underlying database transaction rather than being implemented manually by each Doc_* class.
Engineering Principles¶
Several architectural principles become evident.
- Posting is transactional.
- Validation precedes persistence.
- Partial accounting is never stored.
- Rollback protects accounting integrity.
Doc_*implementations generate accounting but do not manage transactions.- Transaction control belongs to the Posting Engine.
Key Takeaways¶
createFacts()builds accounting in memory.- Validation occurs before persistence.
- Every
Factmust balance. - Posting executes inside a single database transaction.
- Rollback prevents partial accounting.
FACT_ACCTis updated only after successful validation.- Transaction management is centralized in the Accounting Engine.
Next Chapter¶
Chapter 12 explores Accounting Dimensions and C_ValidCombination, explaining how a single accounting combination expands into the multiple dimensions stored within each FactLine.
Revision History¶
| Version | Date | Description |
|---|---|---|
| 1.1 | 2026-06-26 | Added Posting Lifecycle and Transaction Management. |