Architecture Decision Records (ADRs)

This directory contains architecture decisions for the iDempiere CLI.

Active ADRs

Core Architecture

Application Dictionary

API & Integration

AI & MCP Integration

DevOps & Deployment

Implementation Status

ADR Process

We follow the MADR 3.0 (Markdown Any Decision Records) format.

1. Propose: Use 000-template.md to draft new ADR
2. Discuss: Review with team
3. Decide: Update status to Accepted/Rejected
4. Implement: Link to implementation commits
5. Update Index: Add to this README

ADR Format (MADR 3.0)

Each ADR includes:

• Status: Proposed, Accepted, Deprecated, Superseded
• Date: Decision date (YYYY-MM-DD)
• Deciders: People involved in the decision
• Context and Problem Statement: Problem description (required)
• Decision Drivers: Key factors influencing the decision
• Considered Options: Options evaluated (required)
• Decision Outcome: What was decided and why (required)
• Confirmation: How to verify implementation
• Pros and Cons: Analysis of each option
• More Information: Implementation details, diagrams, references

Key Decisions Summary

Core Architecture

ADR-001: iDempiere Version Compatibility

• Maven profiles for v10, v11, v12, v13, Custom Fork
• Version-aware template generation
• Field type validation by iDempiere version
• Branch-to-dependency mapping

ADR-002: CLI Plugin Architecture

• Plugin SPI (Service Provider Interface)
• GeneratorProvider, AnalyzerProvider, IntegrationProvider
• AI service abstraction (Claude, OpenAI, local)
• Directory-based plugin discovery

ADR-003: Generator Architecture (Nx Patterns)

• Virtual File System (GeneratorTree)
• Schema-driven validation (JSON schemas)
• Composable generators (invoke pattern)
• AST manipulation (JavaParser)
• Interactive prompts

ADR-019: CLI Command Structure Redesign

• Prefix-based grouping: dev, dict, gen, pack, ide, env, server, ai, util
• dict for Application Dictionary (clear name vs. ambiguous ad)
• env for DevOps: backup, restore, deploy, clone environments
• AI/LLM native understanding with snake_case MCP tool names
• CLI-to-MCP tool mapping (e.g., dict table add → dict_table_add)
• JSON output with --json for M2M/AI consumption
• Structured error messages with suggestions for AI recovery

Application Dictionary

ADR-004: Enhanced Table Creation

• Standard column templates (audit, document, accounting)
• Auto-create Window/Tab/Fields
• Import table pattern (I_*)
• High-volume table support

ADR-005: Migration Script Architecture

• Document iDempiere's two-phase migration system
• CLI generates preview DDL, not official scripts
• 2Pack XML as primary export format
• Centralized ID management awareness

ADR-008: Application Dictionary Registry

• registry command for AD queries
• JSON export for AI/MCP consumption
• Standard patterns (document, master-data, transaction-line)
• Direct database access via JDBC

ADR-017: AD_Element Description Management

• element describe command for generating AD_Element documentation
• Pattern-based generation for predictable columns (_UU, _ID, Is*, Qty*, Amt*, Date*, _Acct)
• Java code analysis to extract business logic context
• AI agent integration for complex descriptions
• Migration script generation for PostgreSQL/Oracle
• Adopts proven Python scripts from iDempiere repo

ADR-062: Centralized ID Management Integration

• Integrate with iDempiere's centralized ID server (developer.idempiere.com)
• Automatic ID allocation for AD elements based on entity type
• Support for custom implementor ID servers
• Three modes: centralized (HTTP), proxied (via iDempiere REST), local (development)
• Entity type validation and registration
• Prevents ID conflicts in distributed development teams
• Future: CloudEmpiere internal IDs via StorageAdapter (ADR-063)

ADR-063: Hub Storage Adapter Service

• Generic key-value storage interface for Hub services
• Pluggable backends: PostgreSQL (default), AWS DynamoDB, S3, In-Memory (testing)
• Namespace isolation for different concerns (ids, config, cache, state)
• Atomic sequence operations for ID generation
• Used by: CentralizedIdService (CE_* entity types), ConfigService, CacheService
• Enables CloudEmpiere-specific ID management without external server dependency

API & Integration

ADR-006: CLI as M2M API

• --json flag for machine-readable output
• Exit codes for scripting
• Batch command support
• n8n/automation integration

ADR-009: OpenAPI REST Client

• Generate type-safe client from OpenAPI spec
• Replace hand-written IdempiereClient
• 70+ endpoints coverage
• OData query parameter support

AI & MCP Integration

ADR-010: MCP Server Plugin Architecture (Superseded by ADR-013)

• Originally proposed external MCP server using MCP Java SDK
• Replaced by LangChain4j @Tool approach in ADR-013
• src/main/java/org/idempiere/cli/mcp/ code is deprecated

ADR-011: cloudempiere.ai Integration

• Deep iDempiere context via cloudempiere.ai plugin
• Role-based security inheritance
• Secure database query execution
• Audit trail integration

ADR-013: LangChain4j Workflow Routing

• Natural language command routing via LangChain4j
• @Tool annotations wrap existing CLI commands
• Multi-provider support (Ollama local, Claude, OpenAI)
• Offline capability with local LLMs
• ask command for AI-powered CLI interaction

ADR-014: Heng Sin's idempiere-mcp Evaluation

• Evaluated hengsin/idempiere-mcp for adoption
• Different architecture: OSGi bundle vs. embedded LangChain4j
• Decision: Not adopting - different deployment model
• Heng Sin's approach: production (inside iDempiere), ours: development (standalone)

ADR-015: REST Data Tools Facade

• RestDataToolLogic facade over GeneratedOpenApiFactory
• Inspired by Heng Sin's tool patterns (ADR-014)
• Tools: searchRecords, getRecord, runProcess, listServerJobs, etc.
• Uses existing OpenAPI client (ADR-009) with LangChain4j @Tool (ADR-013)

ADR-016: MCP Security & Tenant Routing

• Hybrid security model: static config (dev) + tokens (prod)
• SecurityGuard class for centralized access control
• Automatic tenant filter injection for queries
• iDempiere Data Access Level enforcement
• Multi-tenant MCP client configuration via separate tokens

ADR-018: Mattermost Community Knowledge Integration

• Read-only Mattermost API integration for knowledge extraction
• Channels: ~developers, ~support, ~plugins, ~announcements
• Tools: searchMattermost, getChannelHistory, findSimilarDiscussions
• RAG-based answers from community discussions
• Vector embeddings for semantic search of historical posts

Related Documentation

iDempiere References

Wiki Documentation

• Application Dictionary
• REST Web Services
• 2Pack
• Generating Migration Scripts
• Centralized ID Management

OSGi Factory Documentation

• NF9.1 OSGi New Process Factory
• NF9.1 OSGi New Model Factory
• NF9.1 OSGi New Column Callout Factory
• NF9.1 OSGi New Form Factory
• NF9.1 OSGi New Event Handling Annotation

IDE Setup

• Setting up Eclipse
• Development With Intellij
• Running iDempiere within VSCode