Skip to main content

ADR-030: Document Server & KBaaS - Update Proposal

Version: 2.0.0-PROPOSAL
Date: 2025-09-30
Purpose: Enhance KBaaS to serve as central cloud-native documentation hub for both humans and AI agents

Proposed Enhancements to ADR-030​

1. Cloud-Native Document Serving​

Current State (v1.1.0)​

  • Focuses on compliance and regulatory documents
  • Limited to API access for documents
  • No mention of markdown-to-HTML conversion

Proposed Enhancements (v2.0.0)​

New Features:
  - Markdown-to-HTML conversion with syntax highlighting
  - Human-readable HTTPS URLs (e.g., https://docs.coditect.ai/adrs/adr-001)
  - Full-text search interface for humans
  - RSS/Atom feeds for document updates
  - Versioned URLs (e.g., /v1/docs/api-guide)
  - Language-specific documentation (e.g., /en/docs/, /es/docs/)

2. AI Agent Integration​

Enhanced AI Access Patterns​

// New AI-specific endpoints
pub struct AIDocumentRequest {
    agent_id: String,
    agent_type: String,
    session_id: String,
    context: Vec<String>,  // Related docs for context
    format: DocumentFormat, // markdown, json, yaml
}

// Bulk document fetch for agent initialization
POST /api/v1/agents/documents/bulk
{
  "agent_type": "orchestrator",
  "categories": ["adrs", "standards", "playbooks"],
  "format": "markdown"
}

// Context-aware document recommendations
GET /api/v1/agents/recommend?task=kubernetes-deployment

3. Pod-Level Document Caching​

Pod Architecture:
  - Each user pod gets document cache volume
  - Pre-populated with common docs based on workspace type
  - Lazy-loading of additional docs as needed
  - Sync with central server on updates
  
Volume Structure:
  /workspace/.coditect/
    docs/
      cache/
        adrs/
        standards/
        guides/
      index.json
      last-sync.json

4. Document Organization & Migration​

# Current Structure
/home/halcasteel/v4/
  docs/
    architecture/adrs/
    operations/
    guides/
    kbaas/

# Cloud Document Structure
https://docs.coditect.ai/
  /adrs/                    # Architecture Decision Records
  /standards/               # Coding & compliance standards
  /guides/                  # How-to guides
  /reference/               # API & system reference
  /playbooks/              # Operational playbooks
  /agents/                 # Agent documentation
  /tutorials/              # Interactive tutorials

5. Orchestrator Integration​

Orchestrator Capabilities:
  - Query KBaaS for agent instantiation docs
  - Fetch role-specific guidelines
  - Access compliance requirements
  - Pull testing standards
  - Get deployment playbooks

Example Flow:
  1. User: "Deploy API to production"
  2. Orchestrator queries: GET /api/v1/docs/search?q=production+deployment
  3. KBaaS returns: ["deployment-playbook", "k8s-production-guide", "adr-014"]
  4. Orchestrator fetches docs and creates task plan

6. Document Synchronization​

7. Search & Discovery Enhancements​

// Enhanced search with AI understanding
interface SmartSearch {
  query: string;
  context: {
    user_role: string;
    current_task: string;
    workspace_type: string;
    recent_docs: string[];
  };
  filters: {
    doc_type?: string[];
    compliance?: string[];
    language?: string;
    updated_after?: Date;
  };
}

// Returns ranked results with relevance scores
interface SearchResult {
  documents: Document[];
  suggestions: string[];
  related_topics: string[];
  ai_summary: string;
}

8. Human-Readable Features​

Web Interface Features:
  - Clean, searchable documentation portal
  - Syntax highlighting for code blocks
  - Interactive diagrams (Mermaid rendered)
  - Print-friendly CSS
  - Dark/light theme
  - Mobile responsive
  - Offline PWA support

URL Structure:
  https://docs.coditect.ai/
    /                          # Home/search page
    /adrs/001                  # ADR-001
    /guides/kubernetes         # K8s guide
    /api/v2/reference         # API docs
    /search?q=foundationdb    # Search results

9. Implementation Priority​

Phase 1 (Immediate):
  - Markdown to HTML conversion
  - Basic web interface
  - AI agent bulk fetch API
  - Document categorization

Phase 2 (Next Sprint):
  - Pod-level caching
  - Synchronization protocol
  - Search enhancements
  - CDN integration

Phase 3 (Future):
  - ML-powered recommendations
  - Interactive tutorials
  - Multi-language support
  - Offline capabilities

10. Migration Strategy​

# Step 1: Categorize existing docs
find docs/ -name "*.md" -exec ./categorize.sh {} \;

# Step 2: Generate metadata
for doc in $(find docs/ -name "*.md"); do
  ./extract-metadata.sh "$doc" > "${doc}.meta.json"
done

# Step 3: Upload to cloud storage
gsutil -m cp -r docs/ gs://coditect-docs/

# Step 4: Index in FoundationDB
./index-documents.sh gs://coditect-docs/

# Step 5: Enable web serving
kubectl apply -f k8s/doc-server-deployment.yaml

Benefits of Enhanced KBaaS​

For AI Agents​

  • Instant access to all documentation
  • Context-aware document recommendations
  • Bulk fetch for initialization
  • Always up-to-date information

For Human Users​

  • Google-like search for all docs
  • Beautiful rendered documentation
  • No local file management
  • Always current information

For System Architecture​

  • Single source of truth
  • Reduced pod storage requirements
  • Better caching and performance
  • Simplified updates and maintenance

Recommendation​

Update ADR-030 to version 2.0.0 incorporating these enhancements. This positions CODITECT's KBaaS as a true cloud-native documentation platform that serves both AI agents and humans seamlessly, eliminating dependency on local files while providing superior access and search capabilities.

The enhanced KBaaS becomes a critical enabler for:

  1. AI agent intelligence and context
  2. Human developer productivity
  3. Compliance and audit trails
  4. Knowledge preservation and sharing

This aligns with CODITECT's vision of AI-human collaboration in cloud-native development environments.