Added functionality to enable updates for the `wiki_config` field in the `KnowledgeBaseConfig` struct. This includes: 1. **Type Definition Update**: Added `WikiConfig` field to `KnowledgeBaseConfig` to allow JSON unmarshaling during update requests. 2. **Service Layer Enhancement**: Updated the `UpdateKnowledgeBase` method to persist changes to `wiki_config` when provided in the request. 3. **Frontend TypeScript Adjustments**: Enhanced type definitions in the frontend to support `wiki_config`, improving IDE autocomplete and type checking. This fix addresses the critical issue where `wiki_config` was not being updated due to its absence in the `KnowledgeBaseConfig` struct, ensuring proper handling of wiki configurations during knowledge base updates.
10 KiB
Wiki Config Flow - Trace Summary
📋 Executive Summary
I've completed a comprehensive trace of how wiki_config flows from the frontend through the backend to the database in the WeKnora codebase.
Key Finding: ❌ Wiki config UPDATE is broken - can only be set during creation, not updated afterward.
🎯 Three Documents Generated
1. WIKI_CONFIG_FLOW_ANALYSIS.md (16 KB)
Comprehensive technical analysis with all file paths, struct definitions, and code snippets.
Sections:
- Database layer (SQL migration)
- Type definitions (WikiConfig, KnowledgeBase, KnowledgeBaseConfig)
- Handler layer (create vs update)
- Service layer implementation
- Repository layer
- Frontend API
- Flow diagrams (works vs broken)
- Required fixes with code examples
- Summary table
Best for: Full understanding of the system architecture
2. WIKI_CONFIG_QUICK_REFERENCE.md (5.3 KB)
Quick lookup guide for developers implementing the fix.
Sections:
- Critical finding summary
- Why it's broken (struct diagram)
- Files that need changes
- Database path info
- Request/response flows
- Handler/Service code locations
- Frontend integration
- Test cases
Best for: Quick reference during implementation
3. WIKI_CONFIG_FIX.md (8.5 KB)
Complete implementation guide with exact code changes.
Sections:
- Problem statement
- Change 1: Type definition (code diff)
- Change 2: Service layer (code diff)
- Change 3: Frontend types (code diff)
- Testing procedures (curl examples)
- Verification checklist
- Code review checklist
- Rollback plan
- Impact analysis
Best for: Actually implementing the fix
🔍 Findings at a Glance
Database Layer ✅
CREATE TABLE knowledge_bases (
...
wiki_config JSONB ← EXISTS and properly typed
)
File: migrations/versioned/000032_wiki_pages.up.sql (Line 7)
Type Definitions
WikiConfig Struct ✅
type WikiConfig struct {
Enabled bool
AutoIngest bool
SynthesisModelID string
WikiLanguage string
MaxPagesPerIngest int
}
File: internal/types/wiki_page.go (Lines 89-120)
KnowledgeBase Struct ✅
type KnowledgeBase struct {
// ...
WikiConfig *WikiConfig `json:"wiki_config" gorm:"column:wiki_config;type:json"`
// ...
}
File: internal/types/knowledgebase.go (Line 76)
KnowledgeBaseConfig Struct ❌
type KnowledgeBaseConfig struct {
ChunkingConfig ChunkingConfig
ImageProcessingConfig ImageProcessingConfig
FAQConfig *FAQConfig
// ❌ MISSING: WikiConfig *WikiConfig
}
File: internal/types/knowledgebase.go (Lines 99-107)
This is the root cause!
Handler Layer
CreateKnowledgeBase ✅
- File:
internal/handler/knowledgebase.go(Lines 114-147) - Accepts full
types.KnowledgeBasestruct - wiki_config can be sent:
{ name, wiki_config: {...} } - Status: Works perfectly
UpdateKnowledgeBase ❌
- File:
internal/handler/knowledgebase.go(Lines 446-488) - Accepts
UpdateKnowledgeBaseRequestwithConfig: KnowledgeBaseConfig - wiki_config in request:
{ name, config: { wiki_config: {...} } } - Problem: KnowledgeBaseConfig doesn't have WikiConfig field
- Status: Silently ignores wiki_config
Service Layer
CreateKnowledgeBase ✅
- File:
internal/application/service/knowledgebase.go(Lines 73-98) - Receives full KnowledgeBase
- Calls
EnsureDefaults()which validates wiki_config - Status: Works
UpdateKnowledgeBase ❌
- File:
internal/application/service/knowledgebase.go(Lines 265-311) - Receives
config *KnowledgeBaseConfig - No code to update
kb.WikiConfig - Status: Cannot persist updates
Repository Layer ✅
- File:
internal/application/repository/knowledgebase.go CreateKnowledgeBase(): Line 26 - Uses GORM.Create()UpdateKnowledgeBase(): Line 116 - Uses GORM.Save()- Status: Both correctly handle wiki_config if it's set
Frontend API ⚠️
- File:
frontend/src/api/knowledge-base/index.ts createKnowledgeBase(): Lines 11-33 - accepts any data ✅updateKnowledgeBase(): Lines 42-44 - accepts any config ✅- Issue: Type hints don't include wiki_config (but data is sent)
🔄 Flow Diagram
✅ CREATION FLOW (Works)
Frontend sends:
POST /api/v1/knowledge-bases
{ name, type, wiki_config: {...} }
↓
Handler: CreateKnowledgeBase
Parses as types.KnowledgeBase ✅
↓
Service: CreateKnowledgeBase
Receives KB with wiki_config ✅
Calls EnsureDefaults() ✅
↓
Repository: CreateKnowledgeBase
GORM.Create(kb) serializes all fields ✅
↓
Database: wiki_config column populated ✅
❌ UPDATE FLOW (Broken)
Frontend sends:
PUT /api/v1/knowledge-bases/{id}
{ name, config: { wiki_config: {...} } }
↓
Handler: UpdateKnowledgeBase
Parses as UpdateKnowledgeBaseRequest ❌
Config is KnowledgeBaseConfig (no WikiConfig!) ❌
↓
JSON Unmarshaling:
wiki_config field ignored ❌
↓
Service: UpdateKnowledgeBase
Receives config without wiki_config ❌
Never updates kb.WikiConfig ❌
↓
Repository: UpdateKnowledgeBase
GORM.Save(kb) persists OLD wiki_config ❌
↓
Database: wiki_config NOT updated ❌
🛠️ The Fix (3 Changes)
Change 1: Add WikiConfig to KnowledgeBaseConfig
File: internal/types/knowledgebase.go (After line 106)
// Wiki configuration (for document type knowledge bases with wiki feature enabled)
WikiConfig *WikiConfig `yaml:"wiki_config" json:"wiki_config"`
Change 2: Update Service to Persist WikiConfig
File: internal/application/service/knowledgebase.go (After line 296)
if config.WikiConfig != nil {
kb.WikiConfig = config.WikiConfig
}
Change 3: Update Frontend Type Hints
File: frontend/src/api/knowledge-base/index.ts (In createKnowledgeBase)
wiki_config?: {
enabled: boolean;
auto_ingest?: boolean;
synthesis_model_id?: string;
wiki_language?: string;
max_pages_per_ingest?: number;
};
📊 Component Status Matrix
| Component | File | Lines | Current Status | Issue |
|---|---|---|---|---|
| Database Column | 000032_wiki_pages.up.sql |
7 | ✅ Exists | None |
| WikiConfig Type | wiki_page.go |
89-120 | ✅ Defined | None |
| KnowledgeBase Field | knowledgebase.go |
76 | ✅ Has field | None |
| KnowledgeBaseConfig Field | knowledgebase.go |
99-107 | ❌ Missing | ROOT CAUSE |
| CreateKB Handler | knowledgebase.go |
114-147 | ✅ Works | None |
| UpdateKB Handler | knowledgebase.go |
446-488 | ⚠️ Limited | Uses KnowledgeBaseConfig |
| CreateKB Service | knowledgebase.go |
73-98 | ✅ Works | None |
| UpdateKB Service | knowledgebase.go |
265-311 | ❌ Broken | No WikiConfig update |
| Repository | repository/knowledgebase.go |
26-118 | ✅ Works | None |
| Frontend API | api/knowledge-base/index.ts |
Various | ⚠️ Partial | Missing types |
🧪 Test Verification
Before Fix
- ✅ Create KB with wiki_config → Works
- ❌ Update wiki_config → Fails (not persisted)
- ❌ Fetch KB after update → Old value still there
After Fix
- ✅ Create KB with wiki_config → Works
- ✅ Update wiki_config → Works
- ✅ Fetch KB after update → New value correctly persisted
📁 Document Files Location
All documents saved in WeKnora root:
/Users/wizard/code/go/src/git.woa.com/wxg-prc/WeKnora/
├── WIKI_CONFIG_TRACE_SUMMARY.md ← You are here
├── WIKI_CONFIG_FLOW_ANALYSIS.md ← Full technical analysis
├── WIKI_CONFIG_QUICK_REFERENCE.md ← Developer quick reference
└── WIKI_CONFIG_FIX.md ← Implementation guide
🎓 Key Learnings
Architecture Pattern
WeKnora uses a layered architecture:
- Frontend API - TypeScript functions that call HTTP endpoints
- Handler Layer - Gin HTTP handlers that parse requests
- Service Layer - Business logic
- Repository Layer - Database operations using GORM
- Database - PostgreSQL with JSON columns
Request Structure Design
- Creation: Uses full struct (
KnowledgeBase) - more flexible - Update: Uses limited struct (
KnowledgeBaseConfig) - more controlled - Issue: Limited struct was too limited for wiki_config
GORM Behavior
- GORM automatically serializes/deserializes JSON fields using
Value()andScan()methods - All config structs implement these interfaces
- The repository layer is "dumb" - it trusts what the service gives it
✨ Recommendations
- Implement the fix immediately - Very low risk, high impact
- Add integration tests - Test both creation and update flows
- Update API documentation - Document wiki_config in API docs
- Consider using base struct for all config updates - Currently inconsistent between handlers
📞 Questions Answered
1. How does wiki_config get saved during KB creation?
Via full KnowledgeBase struct → Service → Repository → GORM.Create()
2. How does it get updated after creation?
It doesn't - that's the bug! KnowledgeBaseConfig is missing the field.
3. Where is it stored in the database?
knowledge_bases.wiki_config JSONB column
4. What struct definitions are involved?
WikiConfig(source)KnowledgeBase(has WikiConfig field)KnowledgeBaseConfig(missing WikiConfig field - THE BUG)
5. What's the exact code path from frontend to database?
- Frontend sends HTTP request
- Handler parses request into struct
- Service updates the struct
- Repository calls GORM.Save()
- GORM serializes struct to SQL using Value() method
- Database receives JSON in wiki_config column
6. How to fix it?
Add WikiConfig field to KnowledgeBaseConfig + update service layer (2 code changes)
📝 Next Steps
- Review the three generated documents
- Implement the changes using
WIKI_CONFIG_FIX.md - Test using the provided test cases
- Deploy and verify in production
Generated: April 7, 2026 Analysis Depth: Complete code trace with exact file locations and line numbers