ADR-043: Satellite Service Architecture Evolution

Status

Proposed

Date

2025-12-10

Deciders

Cloudempiere AI Team

Context and Problem Statement

The current AI architecture consists of:

com.cloudempiere.ai (OSGi Plugin, Java 11) - Contains all AI logic including:
- Provider management and factory patterns
- Audit logging and metrics
- Cost tracking and budgets
- Guardrails (input/output validation)
- RAG services
- Agent orchestration
- Tool framework
idempiere-cli (Quarkus, Java 17/21) - Separate CLI tool with:
- LangChain4j 1.x integration
- MCP server capabilities
- REST API endpoints
- RAG infrastructure

The problem: Duplicated functionality and version constraints. The OSGi plugin is locked to Java 11/LangChain4j 0.35.0, while idempiere-cli has modern Java 17+ capabilities but lacks the enterprise features (audit, metrics, cost tracking, guardrails).

Key Insight

Rather than building a new "Satellite Service" from scratch, we should extract and migrate the core AI logic from com.cloudempiere.ai into idempiere-cli, transforming it into the Satellite Service.

Decision Drivers

Avoid duplication - Don't maintain two separate AI implementations
Leverage existing code - 131 source files of battle-tested logic
Unblock Java 17+ features - MCP, extended thinking, latest LangChain4j
Preserve enterprise features - Audit, metrics, cost tracking, guardrails
Enable gradual migration - iDempiere can switch providers incrementally
Simplify architecture - One codebase for AI capabilities

Decision Outcome

Extract core AI logic from com.cloudempiere.ai and integrate into idempiere-cli, transforming idempiere-cli into the Chat API Service that:

Exposes OpenAI-compatible REST API (/v1/chat/completions, /v1/embeddings)
Provides all enterprise features (audit, metrics, guardrails)
Supports iDempiere context for multi-tenant security
Runs on Java 17+ with LangChain4j 1.x

Architecture After Migration

┌─────────────────────────────────────────────────────────────────────────────────┐
│                      BEFORE: Duplicated Architecture                             │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│  ┌─────────────────────────────────┐    ┌─────────────────────────────────────┐ │
│  │  com.cloudempiere.ai (Java 11)  │    │    idempiere-cli (Java 17+)         │ │
│  │                                 │    │                                      │ │
│  │  • Provider Management          │    │  • LangChain4j 1.x                  │ │
│  │  • Audit &amp; Metrics              │    │  • MCP Server                       │ │
│  │  • Cost Tracking                │    │  • REST API                         │ │
│  │  • Guardrails                   │    │  • RAG (separate impl)              │ │
│  │  • RAG Services                 │    │  • CLI Commands                     │ │
│  │  • Agent Orchestration          │    │                                      │ │
│  │  • Tool Framework               │    │  ✗ No audit/metrics                 │ │
│  │                                 │    │  ✗ No cost tracking                 │ │
│  │  ✗ Java 11 locked               │    │  ✗ No guardrails                    │ │
│  │  ✗ LangChain4j 0.35.0           │    │                                      │ │
│  └─────────────────────────────────┘    └─────────────────────────────────────┘ │
│                                                                                  │
└─────────────────────────────────────────────────────────────────────────────────┘

                                      │
                                      │  MIGRATION
                                      ▼

┌─────────────────────────────────────────────────────────────────────────────────┐
│                      AFTER: Unified Satellite Architecture                       │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│  ┌─────────────────────────────────┐    ┌─────────────────────────────────────┐ │
│  │  com.cloudempiere.ai (Java 11)  │    │  idempiere-cli → Satellite Service  │ │
│  │  (Thin Bridge Only)             │    │  (Java 17+, LangChain4j 1.x)        │ │
│  │                                 │    │                                      │ │
│  │  • HTTP Client to Satellite     │    │  FROM OSGi Plugin:                  │ │
│  │  • Context extraction           │───▶│  • Provider Management (refactored) │ │
│  │  • iDempiere UI integration     │    │  • Audit &amp; Metrics                  │ │
│  │                                 │    │  • Cost Tracking &amp; Budgets          │ │
│  │  Minimal code, delegates        │    │  • Guardrails (Input/Output)        │ │
│  │  all AI to Satellite            │    │  • RAG Services (merged)            │ │
│  │                                 │    │  • Agent Orchestration              │ │
│  └─────────────────────────────────┘    │  • Tool Framework                   │ │
│                                         │                                      │ │
│                                         │  FROM idempiere-cli:                 │ │
│                                         │  • LangChain4j 1.x                  │ │
│                                         │  • MCP Server/Client                │ │
│                                         │  • REST API (OpenAI-compat)         │ │
│                                         │  • CLI Commands                     │ │
│                                         │  • Quarkus framework                │ │
│                                         │                                      │ │
│                                         │  NEW:                                │ │
│                                         │  • /v1/chat/completions             │ │
│                                         │  • /v1/embeddings                   │ │
│                                         │  • iDempiere context headers        │ │
│                                         │  • Multi-tenant support             │ │
│                                         └─────────────────────────────────────┘ │
│                                                                                  │
└─────────────────────────────────────────────────────────────────────────────────┘

Component Migration Matrix

Phase 1: Core DTOs & Models (Week 1)

Component	Source (Java 11)	Target (Java 17+)	Effort
AIRequest	provider/dto/	satellite/dto/	Low
AIResponse	provider/dto/	satellite/dto/	Low
AIMessage	provider/dto/	satellite/dto/	Low
AITokenUsage	provider/dto/	satellite/dto/	Low
AIStreamCallback	provider/dto/	satellite/dto/	Low
AIFunction/Call	provider/dto/	satellite/dto/	Low
AIHealthStatus	provider/dto/	satellite/dto/	Low
AIRateLimitStatus	provider/dto/	satellite/dto/	Low
AIModelCapabilities	provider/dto/	satellite/dto/	Low

Phase 2: Observability & Metrics (Week 2)

Component	Source	Target	Notes
AIMetricsListener	observability/	satellite/observability/	Adapt to Quarkus CDI
CostGuard	observability/	satellite/observability/	Integrate with Micrometer
UsageMetrics DTO	observability/	satellite/observability/	Direct copy
MODEL_PRICING map	observability/	satellite/config/	Externalize to config

Phase 3: Guardrails & Security (Week 3)

Component	Source	Target	Notes
InputGuard	guardrails/	satellite/guardrails/	PII detection patterns
OutputGuard	guardrails/	satellite/guardrails/	Response filtering
ExecutionGuard	guardrails/	satellite/guardrails/	Tool validation
GuardResult	guardrails/	satellite/guardrails/	Direct copy
SecureDatabaseQueryExecutor	database/	satellite/database/	Adapt for remote DB

Phase 4: Context & Routing (Week 4)

Component	Source	Target	Notes
ConversationContextManager	routing/	satellite/context/	TTL caching
EntityExtractor	routing/	satellite/routing/	NL entity extraction
PromptAnalyzer	routing/	satellite/routing/	Intent analysis
SourceDecision	routing/	satellite/routing/	Query routing
iDempiereContext	NEW	satellite/context/	Context DTO

Phase 5: Tool Framework (Week 5)

Component	Source	Target	Notes
ITool interface	tool/	satellite/tool/	Adapt for Quarkus
ToolRegistry	tool/	satellite/tool/	CDI-managed
ToolParameter	tool/	satellite/tool/	Direct copy
ToolPermission	tool/	satellite/tool/	Direct copy
BoundaryValidator	tool/	satellite/tool/	Direct copy

Phase 6: Agent Orchestration (Week 6)

Component	Source	Target	Notes
AgentBoundary	boundary/	satellite/boundary/	Security boundaries
AgentBoundaryRegistry	boundary/	satellite/boundary/	CDI singleton
LangChain4jAgent	agent/	Use Quarkus @RegisterAiService	Major refactor
ERPAgent	agent/	satellite/agent/	Domain-specific

Phase 7: REST API Layer (Week 7)

Component	New	Location	Notes
SatelliteApiResource	Yes	satellite/api/	OpenAI-compatible
ChatCompletionRequest	Yes	satellite/api/dto/	Request DTO
ChatCompletionResponse	Yes	satellite/api/dto/	Response DTO
EmbeddingRequest/Response	Yes	satellite/api/dto/	Embedding DTOs
ModelRouter	Yes	satellite/routing/	Provider routing

What Stays in OSGi Plugin

The com.cloudempiere.ai plugin becomes a thin bridge:

// Simplified OSGi plugin after migration
com.cloudempiere.ai/
├── bridge/
│   └── SatelliteClient.java        // HTTP client to satellite
├── context/
│   └── WindowContextExtractor.java  // Extract ZK window context
├── component/
│   └── AIChatWidget.java           // UI component (calls bridge)
├── model/
│   └── MAIProvider.java            // Provider config (type=SAT)
└── Activator.java

Consequences

Positive

Single source of truth for AI logic
Modern Java (17+) with full LangChain4j 1.x
MCP support enabled immediately
Battle-tested code preserved
Enterprise features (audit, metrics, guardrails) available
Easier maintenance - one codebase

Negative

Significant refactoring of idempiere-cli required
Breaking changes to idempiere-cli structure
Migration effort ~7 weeks
Testing overhead - need comprehensive tests

Risks

Risk	Mitigation
Breaking idempiere-cli users	Maintain backward compat for CLI commands
Incomplete migration	Phase-based approach with checkpoints
iDempiere integration issues	Keep thin bridge in OSGi plugin
Performance regression	Benchmark before/after

ADR-042: Satellite AI Provider Integration (integration pattern)
ADR-044: Component Extraction Strategy (detailed extraction plan)
ADR-045: idempiere-cli Integration Architecture (target architecture)

References

ADR-043 | Version 1.0 | 2025-12-10 Status: Proposed Next Step: Review with team, then proceed to ADR-044