ADR-049: Project Rebranding - From CLI to AI Hub

Status

PROPOSED - Awaiting approval

Date

2025-12-11

Context and Problem Statement

Identity Crisis: The project started as "idempiere-cli" (a command-line tool for iDempiere plugin development) but has evolved into something much larger - an AI-powered integration hub serving multiple interfaces:

1. CLI - Terminal commands for developers (original purpose)
2. MCP Server - AI assistant integration for Claude Code/Desktop
3. Chat API - REST backend for iDempiere UI (ZK/Angular clients)
4. Shared Intelligence - RAG knowledge base, 40+ tools, multi-provider LLM support

Current confusion:

• Repository name: idempiere-cli
• README title: "iDempiere CLI"
• ADR-048 internally calls it: "iDempiere AI Hub"
• Satellite API: Unclear naming, strange terminology
• CLI is presented as the primary interface when it's actually just one of three

Questions to answer:

1. What is the project's true identity and purpose?
2. Should we rebrand? If yes, to what?
3. How do we restructure documentation to reflect reality?
4. How do we handle the naming transition?

Codebase Analysis

Finding: CLI is only 19% of the codebase. The majority (74%) is shared AI infrastructure that powers all three interfaces.

Decision

Rebrand the project as "iDempiere AI Hub" with the following changes:

1. Project Identity

New Name: iDempiere AI Hub

Tagline: AI-powered integration hub for iDempiere - CLI, MCP server, and chat API in one

Core Value Proposition:

• Bridge iDempiere with modern AI capabilities (Claude, GPT, Ollama, Bedrock)
• Single source of truth for iDempiere AI tools and knowledge
• Multiple interfaces (CLI, MCP, REST API) backed by shared business logic
• Production-ready: guardrails, observability, cost tracking, multi-tenancy

2. Repository Structure

Keep repository name idempiere-cli for:

• GitHub history continuity (247 commits, existing forks, stars)
• Breaking changes to existing users minimized
• Maven artifact ID can stay idempiere-cli

Update branding:

Repository: cloudempiere/idempiere-cli (unchanged)
Maven GAV:  org.cloudempiere:idempiere-cli:1.33.0 (unchanged)
Project Name: iDempiere AI Hub (NEW)
Description: AI-powered integration hub - CLI, MCP, Chat API (NEW)

3. Terminology Changes

Note: "CLI" remains valid when referring specifically to the command-line interface (one of three interfaces).

4. Documentation Restructure

idempiere-cli/
├── README.md
│   └── Title: "iDempiere AI Hub"
│   └── Sections:
│       ├── What is iDempiere AI Hub?
│       ├── Three Interfaces (CLI, MCP, Chat API)
│       ├── Quick Start (all three modes)
│       └── Use Cases
├── docs/
│   ├── VISION.md (NEW)
│   │   ├── Strategic vision
│   │   ├── Use cases for each interface
│   │   └── Roadmap
│   ├── ARCHITECTURE.md (NEW)
│   │   ├── High-level architecture diagram
│   │   ├── Shared core infrastructure
│   │   └── Execution modes
│   ├── interfaces/ (NEW)
│   │   ├── CLI-GUIDE.md → CLI interface documentation
│   │   ├── MCP-GUIDE.md → MCP server setup & usage
│   │   └── CHAT-API-GUIDE.md → Chat API integration
│   ├── USER_GUIDE.md → Focus on CLI commands (existing)
│   ├── FEATURES.md → Feature matrix across all interfaces (existing)
│   └── adr/
│       ├── 048-idempiere-ai-hub-architecture.md (existing)
│       └── 049-project-rebranding-ai-hub.md (this ADR)

5. README Structure (Proposed)

# iDempiere AI Hub

AI-powered integration hub for iDempiere - CLI, MCP server, and chat API in one.

## What is iDempiere AI Hub?

A unified AI platform for iDempiere that provides:
- **40+ AI tools** for Application Dictionary, code generation, queries, RAG
- **Multiple interfaces** - CLI, MCP server, Chat API
- **Shared intelligence** - RAG knowledge base (Wiki, KB, AD metadata)
- **Production-ready** - Guardrails, observability, cost tracking, multi-tenancy
- **Multi-provider** - Ollama, Claude, GPT, AWS Bedrock

## Three Ways to Use It

### 1. CLI - Developer Terminal Interface
```bash
idempiere-cli dict add table XX_MyTable
idempiere-cli gen model XX_MyTable
idempiere-cli ai ask "list C_ tables"

2. MCP Server - AI Assistant Integration

java -Dquarkus.profile=mcp -jar idempiere-hub-runner.jar server mcp
# Connects to Claude Code, Claude Desktop, Continue.dev

3. Chat API - iDempiere UI Backend

java -Dquarkus.profile=chat-api -jar idempiere-hub-runner.jar server chat-api
# Provides REST API for ZK/Angular clients

Architecture

[High-level diagram showing three interfaces backed by shared core]

Quick Start

[Installation, configuration, first steps]

Documentation

• Vision & Use Cases
• Architecture
• CLI Guide
• MCP Server Guide
• Chat API Guide
• User Guide - Detailed CLI commands

## Migration Plan

### Phase 1: Documentation (This Week)

1. **Create new documentation:**
   - [ ] `docs/VISION.md` - Strategic vision
   - [ ] `docs/ARCHITECTURE.md` - High-level architecture
   - [ ] `docs/interfaces/CLI-GUIDE.md` - CLI documentation
   - [ ] `docs/interfaces/MCP-GUIDE.md` - MCP documentation
   - [ ] `docs/interfaces/CHAT-API-GUIDE.md` - Chat API documentation

2. **Update existing documentation:**
   - [ ] `README.md` - Rebrand as "iDempiere AI Hub"
   - [ ] `CHANGELOG.md` - Add rebranding note
   - [ ] `FEATURES.md` - Reorganize by interface

### Phase 2: Code Refactoring (Next Sprint)

1. **Rename classes:**
   - [ ] `SatelliteAgent` → `ChatAgent`
   - [ ] `SatelliteAgentService` → `ChatAgentService`
   - [ ] `SatelliteApiResource` → `ChatApiResource`
   - [ ] `SatelliteHealthResource` → `ChatHealthResource`
   - [ ] Update all references

2. **Rename configuration:**
   - [ ] `satellite` profile → `chat-api` profile
   - [ ] `satellite-config.properties` → `chat-api-config.properties`
   - [ ] Update `application.properties` profile references

3. **Update package names (optional):**
   - Keep: `org.idempiere.cli.satellite` → `org.idempiere.cli.chatapi`
   - Or deprecate and migrate incrementally

### Phase 3: Communication (After Documentation)

1. **Update external resources:**
   - [ ] GitHub repository description
   - [ ] Maven Central description (next release)
   - [ ] Social media announcement
   - [ ] Wiki pages

2. **Migration guide for users:**
   - [ ] Document profile name change (`satellite` → `chat-api`)
   - [ ] Provide backward compatibility shim (if possible)
   - [ ] Add deprecation warnings in logs

## Consequences

### Positive

- ✅ **Clear identity** - Name matches reality (AI Hub, not just CLI)
- ✅ **Better positioning** - Markets all three interfaces equally
- ✅ **Easier onboarding** - Users understand full capabilities upfront
- ✅ **Accurate documentation** - No more confusion about project scope
- ✅ **Future-proof** - Room to add more interfaces (GraphQL? gRPC?)
- ✅ **Professional branding** - "AI Hub" conveys comprehensive platform

### Negative

- ⚠️ **User confusion** - Existing users may be confused by name change
- ⚠️ **Documentation work** - Significant documentation rewrite needed
- ⚠️ **Code refactoring** - Renaming "Satellite" to "Chat API" across codebase
- ⚠️ **Backward compatibility** - Need to support old profile names temporarily

### Neutral

- 🔄 **Repository name stays** - `idempiere-cli` unchanged (continuity)
- 🔄 **Maven artifact ID stays** - `idempiere-cli` unchanged (compatibility)
- 🔄 **CLI commands unchanged** - Existing CLI workflows work as-is

## Risks & Mitigation

| Risk | Impact | Mitigation |
|------|--------|------------|
| **User confusion** | Medium | Clear migration guide, deprecation warnings |
| **Breaking changes** | High | Maintain backward compatibility for 2-3 versions |
| **Documentation debt** | Medium | Phased approach, prioritize critical docs first |
| **Lost GitHub visibility** | Low | Repository name unchanged, redirect old links |
| **Community backlash** | Low | Communicate rationale clearly, listen to feedback |

## Alternatives Considered

### Alternative 1: Keep "iDempiere CLI" Name
**Pros:** No change, no confusion
**Cons:** Misleading, doesn't reflect 74% of codebase, limits growth
**Decision:** Rejected - Name no longer matches reality

### Alternative 2: Create New Repository "idempiere-ai-hub"
**Pros:** Clean slate, no legacy baggage
**Cons:** Lose GitHub history, stars, forks; user migration pain
**Decision:** Rejected - Too disruptive

### Alternative 3: Rename to "iDempiere AI Platform"
**Pros:** Professional, comprehensive
**Cons:** "Platform" is overused, too enterprise-y, less clear than "Hub"
**Decision:** Rejected - "Hub" better conveys integration/bridging

### Alternative 4: Use "iDempiere AI Gateway"
**Pros:** Emphasizes bridging function
**Cons:** Implies pass-through only, doesn't capture intelligence/RAG
**Decision:** Rejected - Understates capabilities

### Alternative 5: Gradual Transition Without Rebranding
**Pros:** No breaking changes
**Cons:** Perpetuates confusion, doesn't solve core problem
**Decision:** Rejected - Kicks can down road

## Decision Drivers

1. **Accuracy** - Name should reflect what the project actually is
2. **Clarity** - Users should understand full capabilities immediately
3. **Growth** - Name should accommodate future interfaces/capabilities
4. **Continuity** - Minimize disruption to existing users
5. **Professionalism** - Name should convey production-ready platform

## Related ADRs

- **ADR-048:** iDempiere AI Hub Architecture - Already uses "AI Hub" terminology
- **ADR-010:** MCP Server Architecture
- **ADR-021:** RAG Architecture
- **ADR-023:** Quarkus LangChain4j Migration

## References

- [ADR-048 Analysis](docs/adr/048-idempiere-ai-hub-architecture.md)
- Codebase statistics: 247 files, 19% CLI, 74% shared infrastructure
- User feedback: "I'm confused about what this project is"

## Open Questions

1. **Profile backward compatibility:** How long do we support `satellite` profile?
   - **Proposal:** Support both `satellite` and `chat-api` for 3 versions (v1.33-v1.35), deprecate in v1.36

2. **Maven artifact rename?** Should we publish under new artifact ID?
   - **Proposal:** No - Keep `idempiere-cli` for compatibility, describe as "AI Hub" in metadata

3. **Package rename?** Should `org.idempiere.cli.satellite` → `org.idempiere.cli.chatapi`?
   - **Proposal:** Yes, but phased migration with deprecation warnings

4. **New logo/branding?** Should we create AI Hub logo/graphics?
   - **Proposal:** Nice-to-have, not blocking

## Approval Required

**This ADR requires approval from:**
- [ ] Project maintainer (norbertbede)
- [ ] Active contributors (if any)
- [ ] Early adopters / users (feedback welcome)

**Approval criteria:**
- [ ] Agreement on new name "iDempiere AI Hub"
- [ ] Acceptance of migration plan phases
- [ ] Commitment to documentation rewrite

---

**ADR-049** | Version 1.0 | 2025-12-11
**Status:** PROPOSED
**Next Action:** Review & Approve → Execute Phase 1 (Documentation)