Skip to content

KB-212 – Accounting Engine Architecture

Knowledge Base ID: KB-212
Chapter: 2 - Document Engine
Project: BLACK ERP
Version: 0.2
Status: Draft
Last Updated: 2026-06-26
Applies To: ADempiere 3.9.4

Purpose

This chapter explains how ADempiere transitions a business document into an accounting document.

Before the Accounting Engine can create journal entries, the document must complete its business lifecycle through the Document Engine.

Understanding this layer is essential because accounting always starts after a successful document completion.

Overview

The Document Engine is responsible for controlling the lifecycle of every business document.

Typical supported actions include:

  • Prepare
  • Complete
  • Approve
  • Reject
  • Reverse
  • Void
  • Close
  • Reactivate

Every transactional document follows the same state machine regardless of its business purpose.

High-Level Flow

User Action
      │
      ▼
Process Button
      │
      ▼
DocumentEngine
      │
      ▼
processIt()
      │
      ▼
Document Status Updated
      │
      ▼
Post Immediate?
      │
      ├──────────────► No
      │
      ▼
Accounting Engine

The Accounting Engine is never invoked directly by the user.

Instead, posting becomes possible only after the document successfully reaches the appropriate status.

Document Lifecycle

Most transactional documents follow a similar lifecycle.

Drafted
    │
    ▼
In Progress
    │
    ▼
Completed
    │
    ▼
Closed

Other possible transitions include:

  • Voided
  • Reversed
  • Invalid
  • Waiting Approval

The available transitions depend on the document type.

The DocumentEngine Class

The central coordinator is:

org.compiere.process.DocumentEngine

Its responsibilities include:

  • Validate actions
  • Execute document transitions
  • Call business document methods
  • Maintain document status
  • Trigger post-processing

The Document Engine does not create accounting entries.

Its responsibility ends once the business document reaches its new state.

The DocAction Interface

Business documents implement the DocAction interface.

This interface defines the standard operations available to every document.

Typical methods include:

prepareIt()

completeIt()

voidIt()

reverseCorrectIt()

reverseAccrualIt()

closeIt()

reActivateIt()

Each document provides its own implementation while preserving a common lifecycle.

Business Documents

Examples of classes implementing the document lifecycle include:

Document Java Class
Invoice MInvoice
Payment MPayment
Allocation MAllocationHdr
Shipment MInOut
Inventory MInventory
Movement MMovement
GL Journal MJournal

Although their business rules differ, they all follow the same processing model.

Relationship with the Accounting Engine

Once a document reaches the Completed status, it becomes eligible for posting.

The Accounting Engine later transforms the completed business document into accounting facts.

Business Document
        │
        ▼
Completed
        │
        ▼
Accounting Candidate
        │
        ▼
Doc Factory
        │
        ▼
Doc_*

This separation between business processing and accounting processing is one of ADempiere's key architectural principles.

Design Benefits

Separating the Document Engine from the Accounting Engine provides several advantages:

  • Business logic remains independent of accounting.
  • Different accounting schemas can coexist.
  • Posting rules can evolve without modifying business processes.
  • Custom accounting implementations can extend the standard behavior.

The Mexican VAT Cash Basis implementation is an example of extending the accounting layer while leaving the business lifecycle unchanged.

Engineering Notes

When debugging posting issues, always determine first whether the problem belongs to:

  • Business processing (Document Engine), or
  • Accounting processing (Accounting Engine).

Many apparent accounting problems actually originate from documents that never completed successfully.

Next Chapter

Chapter 3 explains how completed documents are transformed into accounting documents by the Posting Engine and the Doc Factory.

Revision History

Version Date Description
0.2 2026-06-26 Added Document Engine architecture.