ADR-068: Unified Knowledge System Architecture
Status
Superseded - Split into focused ADRs (070-073)
Date
2025-12-26 (original), 2025-12-27 (split)
Context
The iDempiere Hub requires a comprehensive knowledge management system to support AI-powered development assistance. The original ADR-068 was too broad, covering:
- Multi-domain RAG architecture
- Query routing and federated search
- Documentation generation pipeline
- Web-based documentation server
- Security, RBAC, and rate limiting
Following ADR best practices (one decision per ADR), this umbrella ADR has been split into focused child ADRs.
Decision
ADR-068 serves as the parent architecture overview. Implementation details are in:
| ADR | Focus | Status |
|---|---|---|
| ADR-070 | Multi-Domain RAG & Query Routing | Proposed |
| ADR-071 | Documentation Generation Pipeline | Proposed |
| ADR-072 | Qute Web Documentation Server | Accepted (working) |
| ADR-073 | Security, RBAC, Rate Limiting | Proposed |
Architecture Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ UNIFIED KNOWLEDGE SYSTEM │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ KNOWLEDGE DOMAINS (ADR-070) │ │
│ │ idempiere │ cloudempiere │ angular │ mobile │ business │ support │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ DOC PIPELINE (ADR-071) │ │
│ │ Sources → AI Analysis → JSON → Qute Templates → Markdown → Git │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────┼─────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ DOCS SERVER │ │ RAG INGEST │ │ MCP SERVER │ │
│ │ (ADR-072) │ │ (pgvector) │ │ (ADR-073) │ │
│ │ Qute Web │ │ Embeddings │ │ + Security │ │
│ │ /docs/* │ │ cli_embeddings │ │ OIDC + RBAC │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Implementation Status
| Component | ADR | Implementation | Status |
|---|---|---|---|
| Domain Schema | 070 | V1__multi_domain_knowledge_schema.sql |
Created |
| Query Router | 070 | QueryRouter.java |
Implemented |
| Federated Search | 070 | FederatedSearchService.java |
Implemented |
| Domain Access | 073 | DomainAccessService.java |
Implemented |
| Docs Resource | 072 | DocsResource.java |
Working |
| Table Generator | 072 | TableDocGenerator.java |
Working |
| Windows List | 072 | windowsList.html |
Working |
| Processes List | 072 | processesList.html |
Working |
| ADR Viewer | 072 | adrView.html |
Working |
| Doc Pipeline | 071 | DocGenerationService.java |
Not implemented |
| Rate Limiter | 073 | RateLimiter.java |
Stub |
| OIDC Auth | 073 | - | Not configured |
Source Documents
The architecture was derived from design documents in docs/ref/:
| Document | Maps To |
|---|---|
multi-domain-rag-architecture.md |
ADR-070 |
documentation-pipeline-architecture.md |
ADR-071 |
llm-direct-documentation.md |
ADR-071 |
quarkus-docs-server-architecture.md |
ADR-072 |
mcp-security-architecture.md |
ADR-073 |
Consequences
Benefits of Split
- Each ADR addresses one architectural decision
- Easier to track implementation status per component
- Can accept/reject individual ADRs independently
- Clearer ownership and scope
Implementation Priority
- ADR-072 (Qute Web) - Already working, continue enhancing
- ADR-070 (Multi-Domain) - Wire FederatedSearchService into MCP
- ADR-073 (Security) - Add OIDC when ready for production
- ADR-071 (Doc Pipeline) - Future automation