KB-212 – Accounting Engine Architecture¶

Knowledge Base ID: KB-212
Chapter: 17 - Architectural Review & Engineering Reference Manual
Project: BLACK ERP
Version: 1.0 (Release Candidate)
Status: Released
Last Updated: 2026-06-27
Applies To: ADempiere 3.9.4

BLACK ERP Engineering Knowledge Base¶

Accounting Engine Architecture¶

Reference Manual¶

This document represents the architectural conclusion of the Accounting Engine research performed during the BLACK ERP implementation project.

Unlike traditional documentation based solely on functional descriptions, this Knowledge Base has been built through:

ADempiere 3.9.4 Source Code Inspection
Runtime Analysis
Database Analysis
Deployment Validation
Packaging Analysis
Digital Signature Validation
Production Engineering Experience

The objective is to provide future BLACK ERP developers with a complete architectural understanding of the Accounting Engine and its interaction with the Core Framework.

Executive Summary¶

The Accounting Engine is one of the most important subsystems of ADempiere.

Its responsibility is to transform business transactions into accounting entries while preserving transactional consistency, accounting integrity and database reliability.

Although accounting posting appears to be an isolated subsystem, source code inspection demonstrates that it depends on multiple Core components working together.

The Accounting Engine therefore cannot be understood in isolation.

Instead, it should be viewed as one layer within a larger architectural framework.

Complete Architecture¶

The following diagram summarizes the complete execution flow documented throughout KB-212.

Business Document

↓

Document Engine

↓

Accounting Engine

↓

Doc

↓

Fact

↓

FactLine

↓

Account Resolution

↓

MAccount

↓

Persistence Framework

↓

PO

↓

Transaction Manager

↓

Trx

↓

Database Layer

↓

DB

↓

PostgreSQL

↓

Cache Layer

↓

CCache

↓

CacheMgt

This diagram represents the complete architectural path followed during document posting.

Every component documented throughout KB-212 participates somewhere within this execution flow.

Layered Architecture¶

From an engineering perspective, the Accounting Engine is organized into several architectural layers.

Business Layer

↓

Accounting Layer

↓

Persistence Layer

↓

Infrastructure Layer

↓

Database Layer

Each layer has clearly defined responsibilities.

Business Layer¶

Responsible for business transactions.

Typical objects include:

Orders
Invoices
Payments
Allocations
Inventory Documents

These objects initiate accounting processing.

Accounting Layer¶

Responsible for transforming business transactions into accounting facts.

Primary classes:

Doc
Fact
FactLine
MAccount
MAcctSchema

This layer contains accounting rules and account resolution.

Persistence Layer¶

Responsible for persisting every business object.

Primary classes:

PO
Query
Generated Models

Persistence logic remains independent from accounting logic.

Infrastructure Layer¶

Responsible for application services.

Primary components:

Trx
DB
CCache
CacheMgt

These services support every subsystem within the ERP.

Database Layer¶

Responsible for physical persistence.

Primary technologies:

JDBC
PostgreSQL

This layer guarantees durability and transactional consistency.

Component Responsibilities Matrix¶

The following table summarizes the primary responsibility of every Core component studied throughout KB-212.

Component	Primary Responsibility	Layer
Business Document	Business Transaction	Business
Document Engine	Document Completion	Business
Doc	Accounting Interpretation	Accounting
Fact	Accounting Entry Generation	Accounting
FactLine	Individual Accounting Line	Accounting
MAccount	Account Resolution	Accounting
MAcctSchema	Accounting Configuration	Accounting
PO	Persistence Framework	Persistence
Query	Object Retrieval	Persistence
Trx	Transaction Management	Infrastructure
DB	Database Abstraction	Infrastructure
PostgreSQL	Physical Storage	Database
CCache	Object Cache	Infrastructure
CacheMgt	Global Cache Administration	Infrastructure

Complete Execution Flow¶

The following diagram summarizes the complete execution sequence observed during source code inspection.

User

↓

Complete Document

↓

Document Engine

↓

Doc subclass

↓

Load Accounting Schema

↓

Resolve Accounts

↓

Generate Fact

↓

Generate FactLines

↓

Persist Business Objects

↓

PO.save()

↓

Transaction

↓

Trx.commit()

↓

DB Layer

↓

PostgreSQL COMMIT

↓

Cache Reset (if required)

↓

End

This sequence represents the complete lifecycle of a typical accounting transaction.

Component Interaction¶

The following diagram illustrates how the principal Core components collaborate during document posting.

Business Document
        │
        ▼
       Doc
        │
        ▼
      Fact
        │
        ▼
    FactLine
        │
        ▼
    MAccount
        │
        ▼
 MAcctSchema
        │
        ▼
        PO
        │
        ▼
       Trx
        │
        ▼
        DB
        │
        ▼
 PostgreSQL

Supporting services remain active throughout execution.

The cache subsystem supports nearly every layer of the application.

Extension Points¶

One of the objectives of this Knowledge Base was identifying the safest extension points for future BLACK ERP development.

Recommended extension points include:

Doc subclasses
Model Validators
Processes
Callouts
Localization Components
New Business Models
API Services
Custom Posting Logic

These components provide stable extension mechanisms while minimizing Core modifications.

Components That Should Rarely Be Modified¶

The following components are fundamental to the stability of the ERP and should only be modified with a complete understanding of their impact.

PO
Trx
DB
CacheMgt
CCache
Fact
FactLine

Whenever possible, extensions should be implemented around these components rather than modifying them directly.

Engineering Guidelines for BLACK ERP¶

The BLACK ERP project adopts the following engineering principles.

Prefer Extension Over Modification¶

Whenever possible:

Extend existing classes.
Avoid modifying stable Core classes.
Reuse existing services.

Keep Business Logic Isolated¶

Localization rules should remain separated from generic ADempiere functionality.

Example:

MXVATCashBasisEngine

↓

Localization Layer

↓

Accounting Engine

This approach simplifies future upgrades.

Preserve Transaction Integrity¶

Database updates must always execute inside managed transactions.

Avoid manual commits whenever the framework already controls the transaction lifecycle.

Respect Cache Consistency¶

Metadata changes should consider cache invalidation.

Database modifications alone may not immediately become visible until the corresponding cache has been refreshed.

Maintain Deployment Discipline¶

Every Core modification should follow the validated deployment sequence.

Source Code

↓

Compile

↓

setupALib

↓

clientDistribute

↓

Restart

↓

Validation

↓

Production

Skipping any deployment step may produce inconsistent runtime behavior.

Development Workflow Adopted by BLACK ERP¶

Throughout this project the following workflow proved reliable.

Requirement

↓

Architecture Analysis

↓

Source Code Inspection

↓

Development

↓

Compilation

↓

Deployment

↓

Validation

↓

Documentation

↓

Git Commit

This process minimizes implementation risk while maintaining complete traceability.

Lessons Learned¶

The research performed during the development of KB-212 produced several important engineering conclusions.

These lessons were obtained through direct source code inspection, deployment validation and real-world implementation experience during the BLACK ERP project.

Accounting Is Only One Layer¶

Initially, the Accounting Engine appeared to be an isolated subsystem.

Source code inspection demonstrated that accounting posting depends on multiple Core services including:

Persistence Framework
Transaction Manager
Database Layer
Cache Architecture

Understanding only the accounting classes is insufficient for safely modifying the ERP.

Source Code Is the Ultimate Documentation¶

Throughout this Knowledge Base, several architectural assumptions were corrected after inspecting the actual ADempiere source code.

Examples include:

PO lifecycle
Transaction management
setupALib packaging
Digital signature process
CCache implementation
CacheMgt behavior

Engineering decisions should always be validated against the source code whenever possible.

Deployment Is Part of Development¶

Developing new functionality is only one part of the engineering process.

Reliable deployment requires:

Successful compilation
setupALib execution
Package signing
clientDistribute execution
Runtime validation
Functional testing

Skipping any deployment stage may result in inconsistent runtime behavior.

Simplicity Is a Core Design Principle¶

Several Core components intentionally implement relatively simple designs.

Examples include:

CCache extending HashMap
CacheMgt using ArrayList
Trx wrapping JDBC transactions
PO encapsulating persistence

The overall robustness of ADempiere results from consistent architectural design rather than algorithmic complexity.

Documentation Must Follow Engineering¶

The methodology adopted during this project proved highly effective.

Rather than documenting assumptions, documentation was produced only after:

Inspecting the source code
Executing runtime validation
Confirming database behavior
Verifying deployment procedures

This methodology significantly increased the quality and accuracy of the Knowledge Base.

Architectural Decisions¶

The following engineering decisions were adopted for BLACK ERP.

Preserve ADempiere Core whenever possible.
Extend rather than replace existing functionality.
Keep localization isolated from generic Core logic.
Maintain deployment discipline.
Validate every architectural assumption through source code inspection.
Document every significant engineering decision.

These principles will guide future BLACK ERP development.

Future Development¶

The completion of KB-212 establishes the technical foundation for future engineering work.

Recommended future Knowledge Bases include:

KB-300 — BLACK ERP Architecture
KB-301 — REST API Architecture
KB-302 — CFDI Engine
KB-303 — SAT Localization
KB-304 — BlackNet Integration
KB-305 — AI Integration Framework

These documents will build upon the architectural knowledge established by KB-212.

Final Conclusions¶

The primary objective of KB-212 was to understand the Accounting Engine sufficiently to perform safe Core modifications.

This objective has been achieved.

The research documented throughout this Knowledge Base provides a complete architectural path covering:

Business Documents
Document Engine
Accounting Engine
Persistence Framework
Transaction Manager
Database Layer
Cache Architecture
Deployment Process

Together, these components describe the complete execution path followed by ADempiere during accounting posting.

This understanding establishes a solid engineering foundation for future BLACK ERP development.

Official Release¶

BLACK ERP Engineering Knowledge Base

KB-212

Accounting Engine Architecture

Reference Manual

Version 1.0

Status

RELEASED

Acknowledgements¶

This Knowledge Base was produced during the implementation of BLACK ERP through a collaborative engineering process combining:

Source code inspection
Runtime validation
Database analysis
Deployment testing
Architecture review
Functional implementation

Its purpose is to preserve engineering knowledge and facilitate future development while reducing implementation risk.

Revision History¶

Version	Date	Description
0.1	Initial research	Accounting Engine investigation
0.5	Source code inspection	Core architecture validation
0.8	Runtime and deployment analysis	Engineering validation
1.0	2026-06-27	Official release of the BLACK ERP Accounting Engine Architecture Reference Manual