ADR-076: Centralized Documentation Repository

Status

Proposed

Date

2025-12-31

Context

Documentation is currently scattered across multiple repositories:

• idempiere-hub: 208 markdown files (ADRs, guides, research, references)
• cloudempiere-workspace: Skills, agents, conventions
• Client plugins: Individual docs per plugin
• Angular frontend: Component documentation

This fragmentation causes:

1. Discovery problems: Hard to find existing documentation
2. Duplication: Same topics documented differently in multiple places
3. Inconsistency: No unified style or structure
4. RAG limitations: Knowledge base ingestion requires scanning multiple repos

Decision

Create a centralized documentation repository (cloudempiere-docs) that:

1. Single source of truth for all CloudEmpiere documentation
2. Aggregates content from multiple source repositories
3. Serves as the knowledge base for RAG/AI assistants
4. Replaces docs/ folders in individual projects

Repository Structure

cloudempiere-docs/
├── README.md
├── mkdocs.yml                    # or docusaurus.config.js
│
├── architecture/
│   ├── decisions/                # ADRs from all projects
│   │   ├── idempiere-hub/        # ADR-001 to ADR-076+
│   │   ├── frontend/             # Frontend ADRs
│   │   └── plugins/              # Plugin ADRs
│   ├── patterns/                 # Shared patterns
│   └── diagrams/                 # Architecture diagrams
│
├── guides/
│   ├── getting-started/          # Onboarding guides
│   ├── development/              # Developer guides
│   ├── deployment/               # DevOps guides
│   └── consulting/               # Consultant workflows
│
├── reference/
│   ├── application-dictionary/   # AD documentation
│   ├── api/                      # API references
│   ├── cli/                      # CLI command reference
│   └── mcp-tools/                # MCP tool documentation
│
├── knowledge-base/
│   ├── idempiere/                # iDempiere core knowledge
│   ├── support/                  # Support KB articles
│   └── troubleshooting/          # Problem/solution pairs
│
├── research/
│   ├── completed/                # Finished research
│   └── active/                   # Ongoing research
│
├── cheatsheets/                  # Quick reference guides
│
└── templates/                    # Document templates
    ├── adr-template.md
    ├── guide-template.md
    └── kb-article-template.md

Content Categories

Migration Strategy

Phase 1: Repository Setup

1. Create cloudempiere-docs repository
2. Set up MkDocs or Docusaurus structure
3. Configure GitHub Pages deployment

Phase 2: Content Migration

1. Move ADRs from idempiere-hub (preserve numbering)
2. Move guides and references
3. Move research documents
4. Update cross-references

Phase 3: Source Repo Cleanup

1. Remove migrated docs/ from idempiere-hub
2. Add symlink or redirect to central repo
3. Update README with link to docs

Phase 4: Integration

1. Configure RAG ingestion from cloudempiere-docs
2. Update docs server to serve from central repo
3. Set up CI/CD for docs deployment

What Stays in Source Repos

Some documentation should remain in source repositories:

Naming Conventions

ADRs in central repo maintain their original numbering with source prefix:

architecture/decisions/idempiere-hub/076-centralized-documentation.md
architecture/decisions/frontend/001-angular-architecture.md

Documentation Server Integration

The server docs command will be updated to:

1. Clone/pull cloudempiere-docs repo on startup
2. Serve documentation from cloned content
3. Support hot-reload for local development

// DocsServerCommand.java update
@Option(names = "--docs-repo",
        defaultValue = "https://github.com/cloudempiere/cloudempiere-docs")
String docsRepo;

RAG Integration

The knowledge ingestion pipeline will:

1. Index cloudempiere-docs as primary source
2. Use directory structure for domain classification
3. Support incremental updates via GitHub webhooks

Consequences

Positive

• Single source of truth for all documentation
• Better discoverability via unified search
• Consistent structure across all docs
• Simplified RAG with single ingestion source
• Easier maintenance with centralized updates

Negative

• Migration effort to move existing content
• Coordination required for multi-repo contributions
• Potential staleness if not properly maintained
• Git history split from original files

Neutral

• Learning curve for new documentation location
• Need to establish contribution guidelines

References

• cloudempiere-docs-template - Existing template structure
• ADR-068 - Docs server architecture
• ADR-073 - Knowledge security layer