Vapora/crates/vapora-leptos-ui/kogral-audit.md

Kogral Integration Audit

Date: 2026-02-08 Component: vapora-leptos-ui Audit Scope: Kogral/Knowledge Graph integration with Leptos UI library

---

Executive Summary

Finding: No direct Kogral integration in vapora-leptos-ui ✅

The vapora-leptos-ui component library is a presentation layer (UI components) and correctly has no direct dependency on Kogral or the knowledge graph. This is the expected and correct architecture.

Status: ✅ PASS - No integration needed, architecture is sound

---

What is Kogral?

Kogral is an external knowledge management system that stores project knowledge as markdown files:

• Location: ../kogral/.kogral/ (sibling directory to VAPORA)
• Purpose: Persistent storage of guidelines, patterns, and architectural decisions (ADRs)
• Format: Markdown files organized by category

Structure:

kogral/.kogral/
├── guidelines/
│   └── {workflow_name}.md
├── patterns/
│   └── *.md
├── adrs/
│   └── *.md
└── config.json

---

Kogral in VAPORA Architecture

Where Kogral is Used

Backend Only (vapora-workflow-engine):

1. Workflow Orchestrator (vapora-workflow-engine/src/orchestrator.rs)

   • Enriches workflow context with Kogral knowledge before execution
   • Methods:
     • enrich_context_from_kogral() - Main entry point
     • query_kogral_guidelines() - Loads workflow-specific guidelines
     • query_kogral_patterns() - Loads relevant patterns
     • query_kogral_decisions() - Loads recent ADRs

2. CLI Commands (vapora-cli/src/commands.rs)

   • --kogral flag (default: true) to enable/disable Kogral enrichment
   • Workflow execution commands use Kogral by default

Configuration:

export KOGRAL_PATH="/path/to/kogral/.kogral"

Default: ../kogral/.kogral

Where Kogral is NOT Used

Frontend/UI (vapora-leptos-ui, vapora-frontend):

• ❌ No direct Kogral integration
• ❌ No file system access (WASM limitation)
• ✅ This is correct - UI should not access Kogral directly

Why this is correct:

1. Separation of Concerns: UI renders data, backend provides data
2. WASM Limitations: Frontend runs in browser, cannot access local filesystem
3. Security: Frontend should not have direct access to knowledge base
4. Architecture: Kogral enrichment happens server-side, results delivered via API

---

Knowledge Graph vs Kogral

VAPORA has two separate systems:

1. Kogral (External, File-based)

• Purpose: Static project knowledge (guidelines, patterns, ADRs)
• Storage: Markdown files on filesystem
• Access: Backend only, via filesystem reads
• Use Case: Enrich agent context before task execution

2. Knowledge Graph (Internal, Database)

• Module: vapora-knowledge-graph
• Purpose: Dynamic execution history, learning curves, agent performance
• Storage: SurrealDB (temporal KG)
• Access: Backend services, REST API
• Use Case: Track execution history, compute learning curves, analytics

Relationship:

Kogral (Static Knowledge)
   ↓ (enriches context)
Workflow Execution
   ↓ (records execution)
Knowledge Graph (Dynamic History)

---

Audit Findings

✅ Correct: No Frontend Integration

vapora-leptos-ui has:

• ✅ No Kogral dependencies
• ✅ No knowledge graph direct access
• ✅ Pure presentation layer

This is the correct architecture because:

1. Browser Limitations: WASM cannot access filesystem
2. Security: Knowledge base should not be exposed to client
3. Performance: Kogral reads are I/O heavy, should be server-side
4. Caching: Backend can cache Kogral content, frontend cannot

✅ Correct: Backend Integration

vapora-workflow-engine has:

• ✅ Kogral integration via filesystem reads
• ✅ Environment variable configuration (KOGRAL_PATH)
• ✅ Graceful fallback if Kogral unavailable (warns, continues with empty)
• ✅ Context enrichment before agent execution

✅ Correct: Knowledge Graph Separation

vapora-knowledge-graph is:

• ✅ Separate module from Kogral
• ✅ Database-backed (SurrealDB)
• ✅ Tracks execution history (not static knowledge)
• ✅ Provides learning curves and analytics

---

Potential Future Enhancements

While the current architecture is sound, these optional enhancements could improve Kogral integration:

1. Knowledge Base Viewer (Frontend)

Use Case: Developers want to browse guidelines/patterns in UI

Implementation:

// Backend API endpoint
GET /api/v1/knowledge/guidelines/{workflow_name}
GET /api/v1/knowledge/patterns
GET /api/v1/knowledge/adrs

// Frontend component
<KnowledgeViewer workflow="feature_development" />

Benefit: View Kogral content without leaving UI

Priority: Low (CLI access sufficient for now)

2. Kogral Search (Frontend)

Use Case: Search across all Kogral content

Implementation:

// Backend API
POST /api/v1/knowledge/search
{
  "query": "authentication patterns",
  "categories": ["patterns", "adrs"]
}

// Frontend component
<KnowledgeSearch />

Benefit: Discover relevant knowledge quickly

Priority: Medium (valuable for large knowledge bases)

3. Inline Knowledge Hints (Frontend)

Use Case: Show relevant Kogral content inline in task/workflow UI

Implementation:

// In TaskDetailPage
<TaskDetail task={task}>
  <KnowledgeHints task_type={task.task_type} />
</TaskDetail>

// Fetches relevant patterns/guidelines for task type

Benefit: Context-aware knowledge delivery

Priority: Medium (improves discoverability)

4. Kogral Status Indicator (Frontend)

Use Case: Show if Kogral is available/configured

Implementation:

// Backend health check
GET /api/v1/health
{
  "kogral": {
    "enabled": true,
    "path": "/path/to/.kogral",
    "guidelines_count": 12,
    "patterns_count": 8
  }
}

// Frontend indicator
<SystemStatus kogral_enabled={health.kogral.enabled} />

Benefit: Transparency about Kogral availability

Priority: Low (developers know via environment)

---

Kogral Audit Checklist

✅ Architecture

• Frontend correctly has no Kogral dependency
• Backend has Kogral integration in workflow engine
• Knowledge Graph is separate from Kogral
• Environment variable configuration exists (KOGRAL_PATH)
• Graceful fallback when Kogral unavailable

✅ Implementation

• Kogral query functions implemented (query_kogral_guidelines, etc.)
• Context enrichment implemented (enrich_context_from_kogral)
• CLI flag exists (--kogral)
• Documentation exists (docs/features/workflow-orchestrator.md)

✅ Testing

• Unit tests for workflow engine (26 tests pass)
• Integration with NATS for workflow coordination
• ⚠️ No explicit Kogral integration tests (relies on filesystem, hard to mock)

⚠️ Gaps

• No Kogral health check endpoint
• No frontend UI for browsing Kogral content
• No search functionality across Kogral content
• No analytics on Kogral usage (which guidelines/patterns most used)

---

Recommendations

Immediate (Do Now)

✅ None - Current architecture is sound

Short-term (Optional, 1-2 weeks)

1. Add Kogral health check endpoint

   • GET /api/v1/health includes Kogral status
   • Helps debugging configuration issues

2. Document Kogral setup in README

   • Add section on setting up Kogral for VAPORA
   • Explain KOGRAL_PATH environment variable

Long-term (Optional, 1-3 months)

1. Add Knowledge Viewer UI

   • Browse guidelines/patterns/ADRs in frontend
   • Markdown rendering with syntax highlighting

2. Add Kogral search

   • Full-text search across all Kogral content
   • Filter by category (guidelines/patterns/adrs)

3. Add Kogral analytics

   • Track which knowledge is accessed most
   • Identify gaps (task types without guidelines)

---

Conclusion

Audit Result: ✅ PASS

vapora-leptos-ui correctly has no Kogral integration. Kogral is a backend concern (workflow enrichment) and should not be accessed directly from the frontend.

Key Findings:

1. ✅ Architecture is sound (backend-only Kogral access)
2. ✅ Frontend is pure presentation layer (correct)
3. ✅ Knowledge Graph and Kogral are properly separated
4. ✅ Graceful fallback when Kogral unavailable
5. ⚠️ Optional enhancements possible but not required

No action required for vapora-leptos-ui.

---

Audit Completed: 2026-02-08 Auditor: Claude Code (Sonnet 4.5) Status: ✅ PASS (No issues found)