KB-212 – Accounting Engine Architecture¶
Knowledge Base ID: KB-212
Chapter: 10 - Document Posting Patterns (Doc_)
Project: BLACK ERP
Version: 1.0
Status: Draft
Last Updated: 2026-06-26
Applies To:* ADempiere 3.9.4
Purpose¶
This chapter explains how individual accounting document implementations (Doc_*) generate accounting entries while sharing the same Posting Engine.
Although every business document has different accounting rules, all document implementations follow a common architectural pattern inherited from the Doc base class.
Understanding these posting patterns is essential before modifying or extending the Accounting Engine.
The Common Architecture¶
Every accounting document inherits from:
Doc
The inheritance hierarchy looks like:
Doc
│
┌────────────────────┼─────────────────────────┐
│ │ │
▼ ▼ ▼
Doc_Invoice Doc_Payment Doc_AllocationHdr
│ │ │
▼ ▼ ▼
Invoice Logic Payment Logic Allocation Logic
Each subclass only implements its own accounting rules.
Everything else is inherited from Doc.
Standard Posting Pipeline¶
Regardless of document type, every implementation follows the same sequence.
Load Document
↓
Load Accounting Schema
↓
Load Document Lines
↓
Resolve Accounts
↓
Create Fact
↓
Create FactLines
↓
Return Fact[]
The Accounting Engine always executes this workflow.
Only the accounting logic changes.
The createFacts() Contract¶
Every accounting implementation overrides:
createFacts(MAcctSchema as)
This method represents the accounting definition for a specific business document.
Conceptually:
Business Rules
↓
createFacts()
↓
Accounting Entries
No accounting is generated outside this method.
Invoice Posting Pattern¶
Class:
Doc_Invoice
Primary responsibilities:
- Customer Receivable
- Vendor Liability
- Revenue
- Expense
- Tax
- Inventory Clearing
- Charges
Typical flow:
Invoice
↓
Resolve Revenue / Expense
↓
Resolve Tax
↓
Create Debit/Credit Lines
↓
Return Fact
Invoices generally produce the most complex accounting entries because they interact with customers, vendors, taxes and products.
Payment Posting Pattern¶
Class:
Doc_Payment
Primary responsibilities:
- Bank Asset
- Cash
- Unallocated Cash
- Write-Off
- Discounts
- Currency Differences
Typical flow:
Payment
↓
Resolve Bank Account
↓
Resolve Counter Account
↓
Create Cash Movement
↓
Return Fact
Payments affect liquidity accounts rather than inventory or revenue.
Allocation Posting Pattern¶
Class:
Doc_AllocationHdr
Primary responsibilities:
- Match Payments
- Match Invoices
- Discounts
- Write-Offs
- Over/Under Payments
Conceptually:
Payment
+
Invoice
↓
Allocation
↓
Settlement Accounting
Allocations normally do not generate operational accounting.
Instead, they settle previously generated accounting entries.
BLACK ERP Example¶
The Mexican VAT Cash Basis localization extends the Allocation pattern.
Standard flow:
Allocation
↓
Settlement
BLACK ERP flow:
Allocation
↓
Settlement
↓
MXVATCashBasisEngine
↓
VAT Reclassification
↓
FactLines
The localization introduces additional accounting movements while preserving the standard allocation behavior.
Shipment / Receipt Pattern¶
Class:
Doc_InOut
Typical responsibilities:
- Inventory Asset
- Inventory Clearing
- Cost Recognition
Conceptually:
Material Movement
↓
Inventory Accounts
↓
FactLines
No Accounts Receivable or Accounts Payable are generated here.
Inventory Adjustment Pattern¶
Class:
Doc_Inventory
Primary responsibilities:
- Inventory Adjustments
- Physical Inventory
- Inventory Gain/Loss
Typical flow:
Inventory Count
↓
Inventory Difference
↓
Inventory Account
+
Adjustment Account
Inventory Movement Pattern¶
Class:
Doc_Movement
Primary responsibilities:
- Warehouse Transfers
- Internal Inventory Relocation
Typical flow:
Warehouse A
↓
Warehouse B
↓
Inventory Reclassification
Normally no profit or loss is generated.
Match Invoice Pattern¶
Class:
Doc_MatchInv
Purpose:
Match:
Receipt
+
Vendor Invoice
This process supports Purchase Order accrual accounting.
Match Purchase Order Pattern¶
Class:
Doc_MatchPO
Purpose:
Match:
Purchase Order
+
Receipt
Used primarily by inventory accrual processes.
Shared Services¶
Every Doc_* implementation reuses services inherited from Doc.
Examples:
- getAccount()
- getValidCombinationId()
- Currency Conversion
- Precision Handling
- Fact Creation
- Period Validation
This avoids duplicated accounting infrastructure.
Architectural Benefits¶
Using specialized document implementations provides several advantages.
- Single Responsibility
- Easier Maintenance
- Extensible Posting Logic
- Minimal Code Duplication
- Consistent Posting Pipeline
Each accounting document only needs to implement the business rules unique to its own process.
Engineering Notes¶
The BLACK ERP localization demonstrates the intended extension model.
Rather than replacing the Accounting Engine, new accounting behavior is introduced by extending the appropriate Doc_* implementation.
This approach preserves compatibility with future ADempiere upgrades and keeps custom logic isolated from the Core framework.
Key Takeaways¶
- Every accounting document inherits from
Doc. - Every implementation overrides
createFacts(). - The Posting Engine is shared by all documents.
- Only business-specific accounting logic changes.
- BLACK ERP extends
Doc_AllocationHdrwithout modifying the overall Posting Engine.
Next Chapter¶
Chapter 11 explores the complete posting lifecycle from createFacts() to persistence in FACT_ACCT, including validation, balancing and transaction handling.
Revision History¶
| Version | Date | Description |
|---|---|---|
| 1.0 | 2026-06-26 | Added document posting patterns and comparison of major Doc_* implementations. |