ADR-027: Implementation Validation Audit

Status

Living Document (Updated: 2025-12-07)

Purpose

This ADR validates the current implementation against all proposed ADRs and identifies gaps, completed features, and pending work.

Validation Summary

ADR	Title	Status	Implementation
001	iDempiere Version Compatibility	✅ Implemented	Maven profiles -Pv10/v11/v12/v13
002	CLI Plugin Architecture	⚠️ Partial	SPI defined, no plugins yet
003	Generator Architecture	✅ Implemented	Qute templates, generator registry
004	Enhanced Table Creation	✅ Implemented	`dict add table` with prefix notation
005	Migration Script Architecture	✅ Implemented	`pack migration` commands
006	CLI as M2M API	✅ Implemented	Exit codes, --json flag, stdout/stderr
008	Application Dictionary Registry	✅ Implemented	`dict registry` commands
009	OpenAPI REST Client	✅ Implemented	Generated client from openapi.yaml
010	MCP Server Architecture	✅ Implemented	`server mcp` with Quarkus MCP
011	CloudEmpiere AI Integration	⚠️ Partial	LangChain4j integrated, custom agents pending
013	LangChain4j Workflow Routing	✅ Implemented	`ai ask` command with tools
014	iDempiere MCP Evaluation	✅ Implemented	Decision to use Quarkus MCP
015	REST Data Tools Facade	✅ Implemented	RestDataToolLogic
016	MCP Security Tenant Routing	❌ Not Started	Multi-tenant support pending
017	AD Element Description Management	⚠️ Partial	Agent defined, workflow pending
018	Mattermost Knowledge Integration	❌ Not Started	RAG source not implemented
019	CLI Command Structure	✅ Implemented	dev/dict/gen/pack/ide/env/server/ai/util
020	Community DevOps Integration	❌ Not Started	Ansible/Docker/K8s pending
021	RAG Architecture	✅ Implemented	`knowledge` commands, pgvector
022	Shared Embedding Infrastructure	✅ Implemented	Shared logic layer
023	Quarkus LangChain4j Migration	✅ Implemented	Migrated from plain LangChain4j
024	AD Metadata Caching	❌ Not Started	Quarkus Cache proposed
025	LangChain4j Observability	✅ Implemented	`--trace` flag
026	CLI Execution Modes	❌ Not Started	`server api`, `shell` proposed

Detailed Validation

ADR-010: MCP Server Architecture

Status: ✅ Implemented

Requirement	Implemented	Notes
Quarkus MCP Server extension	✅ Yes	quarkus-mcp-server-http
HTTP/SSE transport	✅ Yes	Port 8765
McpRegistryTools	✅ Yes	listTables, describeTable, etc.
McpQueryTools	✅ Yes	executeQuery, explainQuery
McpTableTools	✅ Yes	createTable, syncTable
McpGeneratorTools	✅ Yes	generatePlugin, generateModel
McpDoctorTools	✅ Yes	checkEnvironment, checkApi
McpKnowledgeTools	✅ Yes	searchKnowledge, getKnowledgeStats
Shared Tool Logic Layer	✅ Yes	org.idempiere.cli.ai.shared
`server mcp` command	✅ Yes	Stays running with waitForExit()

ADR-019: CLI Command Structure

Status: ✅ Implemented

Command Group	Implemented	Subcommands
dev	✅ Yes	init, doctor, setup, config
dict	✅ Yes	add, sync, registry, generate, translation
gen	✅ Yes	model, callout, process, event
pack	✅ Yes	out, in, validate, migration
ide	✅ Yes	eclipse, intellij, vscode
env	✅ Yes	backup, restore, deploy, clone, status
server	⚠️ Partial	cache, rest*, workflow, mcp
ai	✅ Yes	ask, generate, models, providers
util	✅ Yes	batch, watch, plugin
knowledge	✅ Yes	init, ingest, search, status, clear, validate

*Note: server rest is a REST CLIENT (queries iDempiere), not a REST API server

ADR-021: RAG Architecture

Status: ✅ Implemented

Requirement	Implemented	Notes
pgvector embedding store	✅ Yes	PostgreSQL extension
Wiki source	✅ Yes	iDempiere wiki pages
K_Entry source	✅ Yes	CloudEmpiere knowledge articles
AD Metadata source	✅ Yes	Tables, windows, processes
Embedding model	✅ Yes	nomic-embed-text (768 dim)
RagService	✅ Yes	Search, ingest, statistics
RagConfig	✅ Yes	Source enablement flags
`knowledge` commands	✅ Yes	init, ingest, search, status, clear, validate

ADR-026: CLI Execution Modes

Status: ❌ Not Started (Proposed)

Mode	Status	Command
One-shot	✅ Exists	All commands exit after execution
MCP Server	✅ Exists	`server mcp` (stays running)
REST API Server	❌ Missing	`server api` (proposed)
Interactive Shell	❌ Missing	`shell` (proposed)

Gap Analysis:

The CLI lacks general-purpose long-running modes for:

Container deployment (only MCP server available)
Remote command execution via HTTP
Interactive debugging sessions

Implementation Gaps

Critical (Blocking Deployment)

Gap	ADR	Impact	Priority
`server api` mode	ADR-026	Cannot deploy in containers for non-AI use	High
`shell` mode	ADR-026	No interactive debugging	Medium

Important (Feature Completeness)

Gap	ADR	Impact	Priority
AD Metadata Caching	ADR-024	Performance on repeated queries	Medium
Multi-tenant MCP	ADR-016	Enterprise deployment	Medium
Mattermost RAG	ADR-018	Knowledge source missing	Low
Community DevOps	ADR-020	Ansible/Docker/K8s integration	Low

Minor (Enhancement)

Gap	ADR	Impact	Priority
CLI Plugins	ADR-002	Extensibility	Low
AD Element Agent	ADR-017	Automation	Low

Current Command Behavior

┌─────────────────────────────────────────────────────────────────┐
│                    Command Execution Modes                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ ONE-SHOT (Exit After Execution)                             ││
│  │                                                              ││
│  │  dev init/doctor/setup/config                               ││
│  │  dict add/sync/registry/generate/translation                ││
│  │  gen model/callout/process/event                            ││
│  │  pack out/in/validate/migration                             ││
│  │  ide eclipse/intellij/vscode                                ││
│  │  env backup/restore/deploy/clone/status                     ││
│  │  server cache/workflow                                      ││
│  │  server rest nodes/jobs/health  ← REST CLIENT (not server)  ││
│  │  ai ask/generate/models/providers                           ││
│  │  util batch/watch/plugin                                    ││
│  │  knowledge init/ingest/search/status/clear/validate         ││
│  └─────────────────────────────────────────────────────────────┘│
│                                                                  │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ LONG-RUNNING (Stay Running)                                 ││
│  │                                                              ││
│  │  server mcp     ✅ EXISTS  (MCP protocol for AI assistants) ││
│  │  server api     ❌ MISSING (REST API for general clients)   ││
│  │  shell          ❌ MISSING (Interactive REPL)               ││
│  └─────────────────────────────────────────────────────────────┘│
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Recommendations

Immediate (v1.55.0)

Implement server api - REST API server exposing CLI tools
- Reuse org.idempiere.cli.ai.shared logic
- JAX-RS endpoints
- Quarkus.waitForExit() to stay running
Implement shell - Interactive REPL
- JLine3 for readline
- Tab completion
- History

Short-term (v1.56.0)

Implement AD Metadata Caching (ADR-024)
- Quarkus Cache + Caffeine
- File persistence for cold starts
Implement Multi-tenant MCP (ADR-016)
- Tenant routing via headers
- Security context propagation

Long-term

Community DevOps (ADR-020)
Mattermost RAG (ADR-018)
CLI Plugins (ADR-002)

Test Coverage

Component	Unit Tests	Integration Tests
RegistryToolLogic	✅ Yes	✅ Yes
RagService	✅ Yes	✅ Yes
McpRegistryTools	✅ Yes	✅ Yes
McpKnowledgeTools	⚠️ Partial	❌ No
Server API	❌ N/A	❌ N/A
Shell	❌ N/A	❌ N/A

References

All ADRs in /docs/adr/
USER_GUIDE.md
FEATURES.md
CHANGELOG.md