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**:
```bash
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**:
```rust
// 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**:
```rust
// 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**:
```rust
// 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**:
```rust
// 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

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

### ✅ Implementation

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

### ✅ Testing

- [x] Unit tests for workflow engine (26 tests pass)
- [x] 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)