KB-209 – ADempiere Runtime Architecture¶

Knowledge Base ID: KB-209
Project: BLACK ERP
Version: 1.0
Status: Certified
Last Updated: 2026-06-26
Applies To: ADempiere 3.9.4

Purpose¶

This document describes the internal runtime architecture of ADempiere as implemented in BLACK ERP.

Its objective is to explain how source code becomes a production runtime and to document the relationship between the development tree, build artifacts, installation package and production environment.

This document is the architectural reference for every Core Java developer.

High-Level Architecture¶

Developer
│
▼
source/
│
▼
Compilation
│
▼
install/build/
│
▼
Runtime Packaging
│
▼
Production Runtime
│
▼
Tomcat
│
▼
WebUI

Source Tree¶

/opt/adempiere/source

Contains the complete development source code.

Major directories:

base/
client/
extend/
db/
migration/
packages/
tools/
install/
utils_dev/

Source code modifications are always performed here.

Base Module¶

source/base

Contains the ERP Core:

Accounting Engine
Posting Engine
Document Processing
Model classes
Persistence layer

Compiling this module produces:

source/base/build

Client Module¶

source/client

Responsible for assembling the runtime classes into:

source/lib/Adempiere.jar

Generated by:

clientDistribute

Important:

This artifact is a compiled build artifact.

It is not yet the certified production runtime.

Installation Build¶

source/install/build/Adempiere

This directory represents a complete installable ADempiere distribution.

It contains:

lib/
packages/
tomcat/
utils/

The runtime packaging process executes here.

Runtime Packaging¶

The certified production runtime is generated using:

setupALib

This process performs additional operations beyond compilation.

It:

Creates packages.jar
Creates AdempiereOriginal.jar
Merges runtime packages
Preserves metadata
Applies digital signatures
Produces the certified Adempiere.jar

Production Runtime¶

The production installation resides at:

/opt/adempiere/Adempiere

It is composed of:

bin/
conf/
lib/
packages/
tomcat/
zkpackages/

This directory represents the certified runtime.

Developers must never modify it directly.

Changes originate from the source tree.

Runtime Flow¶

Modify Java Source
↓
Compile base
↓
Compile client
↓
Generate source/lib/Adempiere.jar
↓
Runtime Packaging (setupALib)
↓
Signed Runtime
↓
Deployment
↓
Restart
↓
Functional Validation

Runtime Libraries¶

Important runtime libraries include:

Adempiere.jar
AdempiereOriginal.jar
packages.jar
patches.jar
customization.jar

Each serves a different purpose during packaging and deployment.

Runtime Packages¶

Additional ERP functionality is delivered through runtime packages.

Examples:

Manufacturing
Warehouse
Fixed Assets
Freight
Distribution
Finance
Payroll

These packages are merged during runtime packaging.

Lessons Learned¶

The MX VAT Cash Basis implementation revealed several important architectural findings:

clientDistribute compiles the application but does not produce the final runtime.
setupALib performs mandatory runtime packaging.
Production libraries include packaged modules absent from the compilation artifact.
Updating only Tomcat libraries without runtime packaging may cause ClassNotFoundException errors.
Runtime architecture must always be understood before modifying the Core.

KB-208 – Core Development Lifecycle
KB-210 – Java Debugging Guide
KB-211 – Packaging & Digital Signatures

Revision History¶

Version	Date	Description
1.0	2026-06-26	Initial certified runtime architecture document.