Skip to content

KB-212 – Accounting Engine Architecture

Knowledge Base ID: KB-212
Chapter: 4 - The Doc Base Class
Project: BLACK ERP
Version: 0.4
Status: Draft
Last Updated: 2026-06-26
Applies To: ADempiere 3.9.4

Purpose

This chapter introduces the Doc class, the foundation of the entire ADempiere Accounting Engine.

Every accounting document generated by ADempiere inherits from this class.

Understanding Doc is essential before studying any specific accounting implementation such as:

  • Doc_Invoice
  • Doc_Payment
  • Doc_AllocationHdr
  • Doc_InOut
  • Doc_Inventory

The Doc class provides the common accounting infrastructure used by every posting process.

Class Location

org.compiere.acct.Doc

Architectural Position

The class sits at the center of the Accounting Engine.

Business Document
        │
        ▼
Document Engine
        │
        ▼
Posting Engine
        │
        ▼
Doc
        │
 ┌──────┼───────────────┐
 │      │               │
 ▼      ▼               ▼
Doc_Invoice
Doc_Payment
Doc_AllocationHdr
        │
        ▼
Fact
        │
        ▼
FactLine
        │
        ▼
FACT_ACCT

Everything below this point belongs exclusively to the Accounting Engine.

Design Philosophy

The Accounting Engine follows one of the fundamental principles of Object-Oriented Design:

Common accounting behavior belongs to the base class.

Only document-specific accounting rules belong to subclasses.

This avoids code duplication and guarantees a consistent posting pipeline.

Responsibilities

The Doc class is responsible for:

  • Loading accounting metadata.
  • Managing document context.
  • Loading accounting schemas.
  • Resolving currencies.
  • Managing posting dates.
  • Managing organizations.
  • Creating accounting facts.
  • Providing helper methods for subclasses.
  • Coordinating the posting lifecycle.

It does not define how an invoice or payment is posted.

That responsibility belongs to the corresponding Doc_* implementation.

Information Managed by Doc

Every accounting document carries common information regardless of its business type.

Examples include:

Information Purpose
Client Accounting context
Organization Organizational accounting
Accounting Date Posting period
Currency Monetary calculations
Accounting Schema Ledger configuration
Document Type Posting rules
Document Status Posting validation

These attributes are available to every subclass.

The Inheritance Model

Every accounting implementation extends the same base class.

                     Doc
                      │
      ┌───────────────┼────────────────┐
      │               │                │
      ▼               ▼                ▼
Doc_Invoice     Doc_Payment    Doc_AllocationHdr
      │               │                │
      ▼               ▼                ▼
Document-specific accounting logic

The subclasses inherit all common accounting functionality and only implement the logic unique to their document type.

Lifecycle

Every posting operation follows the same lifecycle.

Instantiate Doc

↓

Load Document Header

↓

Load Document Lines

↓

Load Accounting Schema

↓

Validate

↓

Create Facts

↓

Return Fact[]

Each stage is coordinated by the base class.

Only the accounting generation itself varies between subclasses.

Abstract Behavior

The Doc class defines a framework that specialized accounting classes complete.

Conceptually:

Load Context

↓

Load Details

↓

Validate

↓

createFacts()

↓

Return Posting Result

The createFacts() method is implemented by each Doc_* subclass because accounting rules differ between document types.

Helper Services

The base class provides a rich set of helper functionality used throughout the Accounting Engine.

Examples include:

  • Currency conversion.
  • Account resolution.
  • Tax calculations.
  • Period validation.
  • Fact creation support.
  • Document metadata.
  • Precision handling.

Without these services every accounting class would need to duplicate substantial amounts of code.

Why This Design Matters

The inheritance model provides several engineering benefits.

  • Consistent posting pipeline.
  • Reduced code duplication.
  • Easier maintenance.
  • Predictable extension points.
  • Safer customization.

The Mexican VAT Cash Basis implementation leverages this architecture by extending Doc_AllocationHdr while continuing to use all common services inherited from Doc.

BLACK ERP Example

Our localization does not replace the Accounting Engine.

Instead, it extends one specialized implementation.

Doc
 │
 ▼
Doc_AllocationHdr
 │
 ▼
MXVATCashBasisEngine
 │
 ▼
FactLines

Because the customization occurs below the Doc layer, every standard accounting service remains available.

This minimizes the impact on future upgrades.

Engineering Notes

When developing accounting customizations:

  • Never duplicate functionality already provided by Doc.
  • Reuse helper methods whenever possible.
  • Keep document-specific logic inside the corresponding Doc_* class.
  • Preserve the standard posting lifecycle.

Following these principles reduces maintenance effort and simplifies future merges with upstream ADempiere versions.

Next Chapter

Chapter 5 explores the Fact and FactLine classes, where accounting entries are constructed before being persisted into FACT_ACCT.

Revision History

Version Date Description
0.4 2026-06-26 Added architecture and responsibilities of the Doc base class.