ADR-008: Application Dictionary Registry

Status: Implemented Date: 2024-11-30 Implemented: 2025-11-30 Context: AI code generation, MCP integration, and CLI operations need comprehensive knowledge of iDempiere's Application Dictionary structure

Context

The idempiere-cli integrates with AI services (Claude) and supports machine-to-machine operations via MCP (Model Context Protocol). These systems need to understand:

1. What AD elements exist - Windows, tables, processes, forms, references
2. How elements relate - Window→Tab→Field→Column relationships
3. Standard patterns - Common column templates, reference types, access levels
4. Naming conventions - Table prefixes, column suffixes, element naming

Without a comprehensive registry, AI and automation tools:

• Generate redundant elements (creating what already exists)
• Miss standard patterns (reinventing common solutions)
• Produce inconsistent naming (violating conventions)
• Fail to leverage existing infrastructure (missing attachment points)

Use Case Examples

Decision

Create an AD Element Registry - a structured knowledge base documenting iDempiere's Application Dictionary elements for AI, MCP, and CLI consumption.

Registry Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                     AD Element Registry Architecture                     │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────────┐     ┌─────────────────┐     ┌───────────────────┐     │
│  │  Static Docs │     │  JSON Schemas   │     │  Dynamic Export   │     │
│  │  (Markdown)  │     │  (Resources)    │     │  (CLI Command)    │     │
│  └──────┬───────┘     └────────┬────────┘     └─────────┬─────────┘     │
│         │                      │                        │               │
│         ▼                      ▼                        ▼               │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                    Registry Service Layer                         │   │
│  │  - Element lookup by ID/Name                                      │   │
│  │  - Pattern matching (find similar)                                │   │
│  │  - Relationship traversal                                         │   │
│  │  - Version-aware queries                                          │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│         │                      │                        │               │
│         ▼                      ▼                        ▼               │
│  ┌─────────────┐     ┌─────────────────┐     ┌───────────────────┐     │
│  │     AI      │     │      MCP        │     │       CLI         │     │
│  │  (Claude)   │     │   (Automation)  │     │    (Commands)     │     │
│  └─────────────┘     └─────────────────┘     └───────────────────┘     │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Registry Components

1. Static Documentation (docs/ad-registry/)

Human-readable reference documentation in Markdown format.

docs/ad-registry/
├── README.md                  # Registry overview and navigation
├── windows/
│   ├── core-windows.md        # Core iDempiere windows (ID < 1000000)
│   ├── window-patterns.md     # Common window design patterns
│   └── window-types.md        # Maintain, Transaction, Query types
├── tables/
│   ├── core-tables.md         # Core tables with descriptions
│   ├── table-patterns.md      # Standard table structures
│   ├── column-templates.md    # Standard column sets
│   └── naming-conventions.md  # XX_ prefix rules, _ID suffix
├── processes/
│   ├── core-processes.md      # Built-in processes
│   ├── process-patterns.md    # Common process types
│   └── report-processes.md    # Jasper report processes
├── references/
│   ├── reference-types.md     # AD_Reference validation types
│   ├── display-types.md       # DisplayType constants
│   └── system-elements.md     # AD_Element standard definitions
├── forms/
│   ├── core-forms.md          # Built-in ZK forms
│   └── form-patterns.md       # Form design patterns
└── patterns/
    ├── document-workflow.md   # DocAction, DocStatus patterns
    ├── audit-trail.md         # Created/Updated columns
    ├── multi-tenancy.md       # AD_Client_ID, AD_Org_ID
    └── tree-hierarchy.md      # Parent_ID, tree structures

2. Machine-Readable Schemas (src/main/resources/ad-registry/)

JSON schemas for programmatic access by AI and MCP.

src/main/resources/ad-registry/
├── schema/
│   ├── ad-element.schema.json    # JSON Schema definitions
│   ├── ad-reference.schema.json
│   └── ad-pattern.schema.json
├── elements/
│   ├── windows.json              # Core window definitions
│   ├── tables.json               # Core table definitions
│   ├── columns.json              # Standard column templates
│   ├── processes.json            # Core process definitions
│   ├── references.json           # AD_Reference types
│   └── display-types.json        # DisplayType mappings
├── patterns/
│   ├── document.json             # Document workflow pattern
│   ├── master-data.json          # Master data pattern
│   ├── transaction.json          # Transaction pattern
│   └── configuration.json        # System config pattern
└── relationships/
    ├── window-table.json         # Window→Table mappings
    ├── table-column.json         # Table→Column relationships
    └── reference-validation.json # Reference→Validation rules

3. Dynamic Export (registry command)

CLI command to export current AD state from running iDempiere.

# Export all windows to JSON
idempiere-cli registry export windows -o ad-registry/windows.json

# Export specific table definition
idempiere-cli registry export table C_BPartner -o bpartner-def.json

# Search registry
idempiere-cli registry search "invoice" --type window

# Show element details
idempiere-cli registry info AD_Window:123

# Refresh static registry from live system
idempiere-cli registry refresh --category tables

Element Categories

Core AD Elements

Relationship Map

AD_Window (1)
    └── AD_Tab (n)
            ├── AD_Table (1)
            │       └── AD_Column (n)
            │               ├── AD_Element (1)
            │               └── AD_Reference (1)
            │                       ├── AD_Ref_List (n) [List validation]
            │                       └── AD_Ref_Table (1) [Table validation]
            └── AD_Field (n)
                    └── AD_Column (1)

AD_Process (1)
    └── AD_Process_Para (n)
            ├── AD_Element (1)
            └── AD_Reference (1)

AD_Form (1)
    └── AD_Menu (1)

AD_Menu (hierarchy)
    ├── AD_Window (optional)
    ├── AD_Process (optional)
    ├── AD_Form (optional)
    └── AD_Menu (parent)

Standard Patterns

Pattern 1: Document Workflow

Tables with document status and workflow capabilities.

{
  "pattern": "document",
  "description": "Document with approval workflow",
  "requiredColumns": [
    {"name": "DocStatus", "reference": "List", "refId": 131},
    {"name": "DocAction", "reference": "List", "refId": 135},
    {"name": "Processed", "reference": "YesNo"},
    {"name": "Posted", "reference": "YesNo"},
    {"name": "C_DocType_ID", "reference": "TableDirect"}
  ],
  "optionalColumns": [
    {"name": "DocumentNo", "reference": "String"},
    {"name": "DateDoc", "reference": "Date"},
    {"name": "DateAcct", "reference": "Date"},
    {"name": "Processing", "reference": "Button"}
  ],
  "tableFlags": {
    "IsDocument": true,
    "IsDeleteable": false
  },
  "examples": ["C_Order", "C_Invoice", "M_InOut", "C_Payment"]
}

Pattern 2: Master Data

Reference/lookup tables for core entities.

{
  "pattern": "master-data",
  "description": "Master data entity (customer, product, etc.)",
  "requiredColumns": [
    {"name": "Value", "reference": "String", "description": "Search key"},
    {"name": "Name", "reference": "String", "mandatory": true},
    {"name": "Description", "reference": "String"},
    {"name": "IsActive", "reference": "YesNo", "default": "Y"}
  ],
  "optionalColumns": [
    {"name": "IsSummary", "reference": "YesNo"},
    {"name": "Parent_ID", "reference": "Table", "description": "For hierarchy"}
  ],
  "tableFlags": {
    "AccessLevel": "3",
    "IsHighVolume": false
  },
  "examples": ["C_BPartner", "M_Product", "C_Project", "AD_User"]
}

Pattern 3: Transaction Line

Line items for document transactions.

{
  "pattern": "transaction-line",
  "description": "Line item for parent document",
  "requiredColumns": [
    {"name": "{Parent}_ID", "reference": "TableDirect", "mandatory": true},
    {"name": "Line", "reference": "Integer", "description": "Line number"},
    {"name": "M_Product_ID", "reference": "Search"},
    {"name": "Qty", "reference": "Quantity"},
    {"name": "C_UOM_ID", "reference": "TableDirect"}
  ],
  "optionalColumns": [
    {"name": "PriceEntered", "reference": "CostPrice"},
    {"name": "PriceActual", "reference": "CostPrice"},
    {"name": "LineNetAmt", "reference": "Amount"},
    {"name": "C_Tax_ID", "reference": "TableDirect"},
    {"name": "Description", "reference": "String"}
  ],
  "tableFlags": {
    "IsDeleteable": true
  },
  "examples": ["C_OrderLine", "C_InvoiceLine", "M_InOutLine"]
}

Reference Types (AD_Reference)

Core reference types that AI/MCP must understand:

Implementation Phases

Phase 1: Static Documentation (Completed)

1. ✅ Document core reference types in ADR
2. ✅ Document standard column templates
3. ✅ Document common patterns (document, master-data, transaction-line, audit-columns)
4. ✅ Add to CLAUDE.md for AI context

Phase 2: JSON Export (Completed - v1.23.0)

1. ✅ Create JSON export format
2. ✅ Export core elements to JSON files
3. ✅ Standard patterns embedded in export
4. ✅ Add to CLI as registry export command

Phase 3: Dynamic Registry Command (Completed - v1.23.0)

1. ✅ Implement registry command with subcommands:
   • registry tables - Query AD tables
   • registry windows - Query AD windows
   • registry processes - Query AD processes
   • registry references - Query AD references
   • registry columns - Query columns for a table
   • registry table - Show table details
   • registry export - Export to JSON files
2. ✅ Direct database access via JDBC
3. ✅ Filter and search capabilities

Phase 4: AI/MCP Integration (Future)

1. Auto-load registry in AI prompts
2. MCP tool for registry queries
3. Pattern suggestion engine
4. Conflict detection (element already exists)

CLI Command Design

registry Command

# List categories
idempiere-cli registry list
# Output: windows, tables, columns, processes, forms, references, patterns

# Export category to JSON
idempiere-cli registry export windows -o windows.json
idempiere-cli registry export tables --filter "C_%" -o core-tables.json

# Search across registry
idempiere-cli registry search "invoice"
idempiere-cli registry search "partner" --type table

# Get element details
idempiere-cli registry info window C_Invoice
idempiere-cli registry info table C_BPartner
idempiere-cli registry info reference 17

# Show pattern details
idempiere-cli registry pattern document
idempiere-cli registry pattern master-data

# Validate element exists
idempiere-cli registry exists table XX_MyTable
# Exit 0 = exists, Exit 1 = not found

# Refresh from live iDempiere
idempiere-cli registry refresh --url http://localhost:8080

Output Formats

# Human-readable (default)
idempiere-cli registry info table C_BPartner

# JSON output
idempiere-cli registry info table C_BPartner --json

# Markdown output (for docs)
idempiere-cli registry export windows --format markdown -o windows.md

AI Integration

Prompt Context Enhancement

When AI generates code, include relevant registry context:

System: You are helping create iDempiere customizations.

Registry Context:
- Table C_BPartner exists (ID=291) with columns: C_BPartner_ID, Value, Name, ...
- Window Business Partner exists (ID=123) with tabs: Partner, Customer, Vendor
- Reference Table Direct (ID=19) is used for direct FK columns
- Pattern "document" requires DocStatus, DocAction, Processed columns

User: Add a custom field to track partner rating on C_BPartner

Pattern Suggestions

User: Create a table for purchase requisitions

AI (with registry):
- Detected pattern: "document" (purchase workflow)
- Similar tables: C_Order, M_Requisition
- Suggested structure:
  - Standard columns (from pattern)
  - Document columns (DocStatus, DocAction, etc.)
  - Parent reference (AD_User_ID for requester)
  - Line table pattern for items

Consequences

Positive

• AI accuracy - Generates context-aware code
• Reduced redundancy - Avoids recreating existing elements
• Pattern consistency - Follows iDempiere conventions
• MCP capabilities - Machine-readable AD knowledge
• Developer reference - Quick lookup for developers

Negative

• Maintenance overhead - Registry must stay current
• Storage requirements - JSON schemas add to CLI size
• Version complexity - Registry varies by iDempiere version
• Initial effort - Significant documentation work

Neutral

• Offline capability - Static registry works offline
• Optional feature - CLI works without registry
• Incremental adoption - Can start with core elements

References

iDempiere Documentation

• Application Dictionary
• Reference (Window ID-101)
• Table and Column (Window ID-100)
• Window, Tab & Field (Window ID-102)

Related ADRs

• ADR-004: Enhanced Table Creation - Column templates
• ADR-006: CLI as M2M API - Automation interface
• ADR-003: Generator Architecture - Code generation patterns
• ADR-053: Build-Time Model Discovery - Uses RegistryToolLogic as foundation for Chat API metadata generation
  • See: 053-build-time-model-discovery-ADR008-comparison.md for integration strategy

Source Code

• DisplayType.java
• X_AD_Reference.java