ADR-077: Multi-Repo Documentation Aggregation

Status

Proposed

Context

CloudEmpiere is a consulting SaaS company with heavy knowledge assets distributed across 10+ repositories. Documentation needs include:

ADRs (Architecture Decision Records) in each repo
References - API docs, integration guides
Guides - How-to docs, tutorials
Audits - Security, compliance docs
Product Design - Requirements, specifications

Audiences

Developers - Technical docs, ADRs, API references
Product Managers - Product design, requirements, roadmaps
Consultants - Client resources, SOPs, implementation guides

Source Repositories (10+)

Repository	ADR Prefix	Content Type
idempiere-hub	ADR-0XX	CLI/MCP/API architecture
nx-frontend	FE-0XX	Angular frontend decisions
ionic-mobile	MOB-0XX	Mobile app architecture
idempiere-plugins	PLG-0XX	Plugin development
cloudempiere-infra	INF-0XX	DevOps, infrastructure
...	...	...

Decision

1. Hybrid Aggregation Model

Use symlinks for local development + CI sync for production:

cloudempiere-docs/
├── content/
│   ├── index.md                    # Landing page
│   ├── getting-started.md          # Onboarding
│   │
│   ├── developers/                 # 🔧 DEVELOPER AUDIENCE
│   │   ├── index.md
│   │   ├── architecture/           # Cross-repo ADR aggregation
│   │   │   ├── index.md            # ADR index with search
│   │   │   ├── idempiere-hub/      # → symlink to ../../../idempiere-hub/docs/adr
│   │   │   ├── nx-frontend/        # → symlink to ../../../nx-frontend/docs/adr
│   │   │   └── ionic-mobile/       # → symlink to ../../../ionic-mobile/docs/adr
│   │   ├── api-reference/
│   │   └── guides/
│   │
│   ├── product/                    # 📋 PRODUCT MANAGER AUDIENCE
│   │   ├── index.md
│   │   ├── roadmap/
│   │   ├── requirements/           # PRDs, specs
│   │   ├── releases/               # Release notes aggregated
│   │   └── analytics/              # Usage metrics, KPIs
│   │
│   ├── consulting/                 # 🤝 CONSULTANT AUDIENCE
│   │   ├── index.md
│   │   ├── client-onboarding/
│   │   ├── workflows/              # SOPs, processes
│   │   ├── support-kb/             # Knowledge base
│   │   └── audits/                 # Security, compliance
│   │
│   ├── idempiere/                  # Core ERP knowledge
│   ├── cloudempiere/               # Hub ecosystem
│   ├── nx-frontend/                # Angular frontend
│   ├── ionic-mobile/               # Mobile app
│   └── cheatsheets/                # Quick references

2. Symlink Configuration

Create docs-config.yaml in cloudempiere-docs root:

# docs-config.yaml
aggregation:
  # Symlink mappings for local development
  symlinks:
    - source: ../idempiere-hub/docs/adr
      target: content/developers/architecture/idempiere-hub
    - source: ../nx-frontend/docs/adr
      target: content/developers/architecture/nx-frontend
    - source: ../ionic-mobile/docs/adr
      target: content/developers/architecture/ionic-mobile
    - source: ../idempiere-hub/CHANGELOG.md
      target: content/product/releases/idempiere-hub.md

  # CI sync for repos not locally available
  ci_sync:
    - repo: cloudempiere/idempiere-plugins
      path: docs/adr
      target: content/developers/architecture/idempiere-plugins

3. ADR Index Generation

Auto-generate ADR index from all symlinked repos:

# Architecture Decision Records

| ID | Title | Status | Product | Date |
|----|-------|--------|---------|------|
| [ADR-077](idempiere-hub/077-multi-repo...) | Multi-Repo Aggregation | Proposed | Hub | 2024-12 |
| [FE-012](nx-frontend/012-state-mgmt...) | State Management | Accepted | Frontend | 2024-11 |

Update base.html sidebar to be audience-aware:

&lt;h3&gt;👤 By Role&lt;/h3&gt;
&lt;ul&gt;
    &lt;li&gt;&lt;a href=&quot;/docs/developers/&quot;&gt;Developers&lt;/a&gt;&lt;/li&gt;
    &lt;li&gt;&lt;a href=&quot;/docs/product/&quot;&gt;Product&lt;/a&gt;&lt;/li&gt;
    &lt;li&gt;&lt;a href=&quot;/docs/consulting/&quot;&gt;Consultants&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;📦 By Product&lt;/h3&gt;
&lt;ul&gt;
    &lt;li&gt;&lt;a href=&quot;/docs/idempiere/&quot;&gt;iDempiere&lt;/a&gt;&lt;/li&gt;
    &lt;li&gt;&lt;a href=&quot;/docs/cloudempiere/&quot;&gt;CloudEmpiere&lt;/a&gt;&lt;/li&gt;
    &lt;li&gt;&lt;a href=&quot;/docs/nx-frontend/&quot;&gt;Nx Frontend&lt;/a&gt;&lt;/li&gt;
    &lt;li&gt;&lt;a href=&quot;/docs/ionic-mobile/&quot;&gt;Ionic Mobile&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

Aggregation Strategies Compared

Strategy	Pros	Cons	Use When
Symlinks	Zero duplication, real-time	Local repos required	Local dev
Git Submodules	Version-pinned	Complex updates	Stable references
CI Sync	Works with remote repos	Stale until sync	Production build
Copy on Release	Simple, controlled	Manual effort	Release notes

Implementation Plan

Phase 1: Local Symlinks (Immediate)

Create audience directories in cloudempiere-docs
Add symlink setup script
Update sidebar navigation

Phase 2: CI Aggregation (Sprint 2)

GitHub Action to sync remote repos
ADR index generator script
Search across all docs

Phase 3: Knowledge Graph (Future)

Cross-reference ADRs
Dependency visualization
AI-powered search via RAG

Consequences

Positive

Single discovery point for all documentation
Audience-specific navigation
No doc duplication (source of truth in each repo)
Scalable to 50+ repos

Negative

Symlink setup required for local dev
CI complexity for production
Cross-repo search requires aggregation

Risks

Broken symlinks if repo structure changes
Stale CI-synced content

References

ADR-076 - Centralized Documentation Repository
Docusaurus Multi-Instance
Backstage TechDocs