stack/docs/design/knowledge-module-issues.md

Knowledge Module - Implementation Issues

Epic: Knowledge Module
Design Doc: knowledge-module.md
Target: 6 weeks
Created: 2025-01-29

---

Epic Overview

Build a native knowledge management module for Mosaic Stack with wiki-style linking, semantic search, and graph visualization.

Labels: epic, feature, knowledge-module

---

Phase 1: Foundation (Week 1-2)

KNOW-001: Database Schema for Knowledge Module

Priority: P0
Estimate: 4h
Labels: database, schema, phase-1

Description: Create Prisma schema and migrations for the Knowledge module.

Acceptance Criteria:

• KnowledgeEntry model with all fields
• KnowledgeEntryVersion model for history
• KnowledgeLink model for wiki-links
• KnowledgeTag and KnowledgeEntryTag models
• KnowledgeEmbedding model (pgvector ready)
• All indexes defined
• Migration runs cleanly
• Seed data for testing

Technical Notes:

• Reference design doc for full schema
• Ensure @@unique([workspaceId, slug]) constraint
• Add search_vector column for full-text search
• pgvector extension may need separate setup

---

KNOW-002: Entry CRUD API Endpoints

Priority: P0
Estimate: 6h
Labels: api, phase-1

Description: Implement RESTful API for knowledge entry management.

Acceptance Criteria:

• POST /api/knowledge/entries - Create entry
• GET /api/knowledge/entries - List entries (paginated, filterable)
• GET /api/knowledge/entries/:slug - Get single entry
• PUT /api/knowledge/entries/:slug - Update entry
• DELETE /api/knowledge/entries/:slug - Archive entry (soft delete)
• Workspace isolation enforced
• Input validation with class-validator
• OpenAPI/Swagger documentation

Technical Notes:

• Follow existing Mosaic API patterns
• Use @WorkspaceGuard() for tenant isolation
• Slug generation from title with collision handling

---

KNOW-003: Tag Management API

Priority: P0
Estimate: 3h
Labels: api, phase-1

Description: Implement tag CRUD and entry-tag associations.

Acceptance Criteria:

• GET /api/knowledge/tags - List workspace tags
• POST /api/knowledge/tags - Create tag
• PUT /api/knowledge/tags/:slug - Update tag
• DELETE /api/knowledge/tags/:slug - Delete tag
• GET /api/knowledge/tags/:slug/entries - Entries with tag
• Entry creation/update accepts tag slugs
• Auto-create tags if autoCreateTags: true

---

KNOW-004: Basic Markdown Rendering

Priority: P0
Estimate: 4h
Labels: api, rendering, phase-1

Description: Render markdown content to HTML with caching.

Acceptance Criteria:

• Markdown-to-HTML conversion on entry save
• Support GFM (tables, task lists, strikethrough)
• Code syntax highlighting (highlight.js or Shiki)
• Sanitize HTML output (XSS prevention)
• Cache rendered HTML in contentHtml field
• Invalidate cache on content update

Technical Notes:

• Use marked or remark for parsing
• Wiki-links ([[...]]) parsed but not resolved yet (Phase 2)

---

KNOW-005: Entry List Page UI

Priority: P0
Estimate: 6h
Labels: frontend, phase-1

Description: Build the knowledge entry list page in the web UI.

Acceptance Criteria:

• List view with title, summary, tags, updated date
• Filter by status (draft/published/archived)
• Filter by tag
• Sort by updated/created/title
• Pagination
• Quick search (client-side filter)
• Create new entry button → editor
• Responsive design

---

KNOW-006: Entry Detail/Editor Page UI

Priority: P0
Estimate: 8h
Labels: frontend, editor, phase-1

Description: Build the entry view and edit page.

Acceptance Criteria:

• View mode with rendered markdown
• Edit mode with markdown editor
• Split view option (edit + preview)
• Title editing
• Tag selection/creation
• Status dropdown
• Save/cancel/delete actions
• Unsaved changes warning
• Keyboard shortcuts (Cmd+S to save)

Technical Notes:

• Consider CodeMirror or Monaco for editor
• May use existing rich-text patterns from Mosaic

---

Phase 2: Linking (Week 2-3)

KNOW-007: Wiki-Link Parser

Priority: P0
Estimate: 4h
Labels: api, parsing, phase-2

Description: Parse [[wiki-link]] syntax from markdown content.

Acceptance Criteria:

• Extract all [[...]] patterns from content
• Support [[slug]] basic syntax
• Support [[slug|display text]] aliased links
• Support [[slug#header]] section links
• Return structured link data with positions
• Handle edge cases (nested brackets, escaping)

Technical Notes:

interface ParsedLink {
  raw: string; // "[[design|Design Doc]]"
  target: string; // "design"
  display: string; // "Design Doc"
  section?: string; // "header" if [[design#header]]
  position: { start: number; end: number };
}

---

KNOW-008: Link Resolution Service

Priority: P0
Estimate: 4h
Labels: api, phase-2

Description: Resolve parsed wiki-links to actual entries.

Acceptance Criteria:

• Resolve by exact slug match
• Resolve by title match (case-insensitive)
• Fuzzy match fallback (optional)
• Mark unresolved links as broken
• Extract surrounding context for link record
• Batch resolution for efficiency

---

KNOW-009: Link Storage and Sync

Priority: P0
Estimate: 4h
Labels: api, database, phase-2

Description: Store links in database and keep in sync with content.

Acceptance Criteria:

• On entry save: parse → resolve → store links
• Remove stale links on update
• GET /api/knowledge/entries/:slug/links/outgoing
• GET /api/knowledge/entries/:slug/links/incoming (backlinks)
• GET /api/knowledge/entries/:slug/links/broken
• Broken link report for workspace

---

KNOW-010: Backlinks Display UI

Priority: P1
Estimate: 3h
Labels: frontend, phase-2

Description: Show incoming links (backlinks) on entry pages.

Acceptance Criteria:

• Backlinks section on entry detail page
• Show linking entry title + context snippet
• Click to navigate to linking entry
• Count badge in sidebar/header
• Empty state when no backlinks

---

KNOW-011: Link Autocomplete in Editor

Priority: P1
Estimate: 6h
Labels: frontend, editor, phase-2

Description: Autocomplete suggestions when typing [[.

Acceptance Criteria:

• Trigger on [[ typed in editor
• Show dropdown with matching entries
• Search by title and slug
• Show recent entries first, then alphabetical
• Insert selected entry as [[slug]] or [[slug|title]]
• Keyboard navigation (arrows, enter, escape)
• Debounced API calls

---

KNOW-012: Render Links in View Mode

Priority: P0
Estimate: 3h
Labels: frontend, rendering, phase-2

Description: Render wiki-links as clickable links in entry view.

Acceptance Criteria:

• [[slug]] renders as link to /knowledge/slug
• [[slug|text]] shows custom text
• Broken links styled differently (red, dashed underline)
• Hover preview (optional, stretch goal)

---

Phase 3: Search (Week 3-4)

KNOW-013: Full-Text Search Setup

Priority: P0
Estimate: 4h
Labels: database, search, phase-3

Description: Set up PostgreSQL full-text search for entries.

Acceptance Criteria:

• Add tsvector column to entries table
• Create GIN index on search vector
• Weight title (A), summary (B), content (C)
• Trigger to update vector on insert/update
• Verify search performance with test data

---

KNOW-014: Search API Endpoint

Priority: P0
Estimate: 4h
Labels: api, search, phase-3

Description: Implement search API with full-text search.

Acceptance Criteria:

• GET /api/knowledge/search?q=...
• Return ranked results with snippets
• Highlight matching terms in snippets
• Filter by tags, status
• Pagination
• Response time < 200ms

---

KNOW-015: Search UI

Priority: P0
Estimate: 6h
Labels: frontend, search, phase-3

Description: Build search interface in web UI.

Acceptance Criteria:

• Search input in knowledge module header
• Search results page
• Highlighted snippets
• Filter sidebar (tags, status)
• "No results" state with suggestions
• Search as you type (debounced)
• Keyboard shortcut (Cmd+K) to focus search

---

KNOW-016: pgvector Setup

Priority: P1
Estimate: 4h
Labels: database, vector, phase-3

Description: Set up pgvector extension for semantic search.

Acceptance Criteria:

• Enable pgvector extension in PostgreSQL
• Create embeddings table with vector column
• HNSW index for fast similarity search
• Verify extension works in dev and prod

Technical Notes:

• May need PostgreSQL 15+ for best pgvector support
• Consider managed options (Supabase, Neon) if self-hosting is complex

---

KNOW-017: Embedding Generation Pipeline

Priority: P1
Estimate: 6h
Labels: api, vector, phase-3

Description: Generate embeddings for entries using OpenAI or local model.

Acceptance Criteria:

• Service to generate embeddings from text
• On entry create/update: queue embedding job
• Background worker processes queue
• Store embedding in database
• Handle API rate limits and errors
• Config for embedding model selection

Technical Notes:

• Start with OpenAI text-embedding-ada-002
• Consider local options (sentence-transformers) for cost/privacy

---

KNOW-018: Semantic Search API

Priority: P1
Estimate: 4h
Labels: api, search, vector, phase-3

Description: Implement semantic (vector) search endpoint.

Acceptance Criteria:

• POST /api/knowledge/search/semantic
• Accept natural language query
• Generate query embedding
• Find similar entries by cosine similarity
• Return results with similarity scores
• Configurable similarity threshold

---

Phase 4: Graph (Week 4-5)

KNOW-019: Graph Data API

Priority: P1
Estimate: 4h
Labels: api, graph, phase-4

Description: API to retrieve knowledge graph data.

Acceptance Criteria:

• GET /api/knowledge/graph - Full graph (nodes + edges)
• GET /api/knowledge/graph/:slug - Subgraph centered on entry
• GET /api/knowledge/graph/stats - Graph statistics
• Include orphan detection
• Filter by tag, status
• Limit node count option

---

KNOW-020: Graph Visualization Component

Priority: P1
Estimate: 8h
Labels: frontend, graph, phase-4

Description: Interactive knowledge graph visualization.

Acceptance Criteria:

• Force-directed graph layout
• Nodes sized by connection count
• Nodes colored by status
• Click node to navigate or show details
• Zoom and pan controls
• Layout toggle (force, hierarchical, radial)
• Performance OK with 500+ nodes

Technical Notes:

• Use D3.js or Cytoscape.js
• Consider WebGL renderer for large graphs

---

KNOW-021: Entry-Centered Graph View

Priority: P2
Estimate: 4h
Labels: frontend, graph, phase-4

Description: Show mini-graph on entry detail page.

Acceptance Criteria:

• Small graph showing entry + direct connections
• 1-2 hop neighbors
• Click to expand or navigate
• Toggle to show/hide on entry page

---

KNOW-022: Graph Statistics Dashboard

Priority: P2
Estimate: 3h
Labels: frontend, graph, phase-4

Description: Dashboard showing knowledge base health.

Acceptance Criteria:

• Total entries, links, tags
• Orphan entry count (no links)
• Broken link count
• Average connections per entry
• Most connected entries
• Recently updated

---

Phase 5: Polish (Week 5-6)

KNOW-023: Version History API

Priority: P1
Estimate: 4h
Labels: api, versioning, phase-5

Description: API for entry version history.

Acceptance Criteria:

• Create version on each save
• GET /api/knowledge/entries/:slug/versions
• GET /api/knowledge/entries/:slug/versions/:v
• POST /api/knowledge/entries/:slug/restore/:v
• Version limit per entry (configurable, default 50)
• Prune old versions

---

KNOW-024: Version History UI

Priority: P1
Estimate: 6h
Labels: frontend, versioning, phase-5

Description: UI to browse and restore versions.

Acceptance Criteria:

• Version list sidebar/panel
• Show version date, author, change note
• Click to view historical version
• Diff view between versions
• Restore button with confirmation
• Compare any two versions

Technical Notes:

• Use diff library for content comparison
• Highlight additions/deletions

---

KNOW-025: Markdown Import

Priority: P2
Estimate: 4h
Labels: api, import, phase-5

Description: Import existing markdown files into knowledge base.

Acceptance Criteria:

• Upload .md file(s)
• Parse frontmatter for metadata
• Generate slug from filename or title
• Resolve wiki-links if target entries exist
• Report on import results
• Bulk import from folder/zip

---

KNOW-026: Export Functionality

Priority: P2
Estimate: 3h
Labels: api, export, phase-5

Description: Export entries to markdown/PDF.

Acceptance Criteria:

• Export single entry as markdown
• Export single entry as PDF
• Bulk export (all or filtered)
• Include frontmatter in markdown export
• Preserve wiki-links in export

---

KNOW-027: Caching Layer

Priority: P1
Estimate: 4h
Labels: api, performance, phase-5

Description: Implement Valkey caching for knowledge module.

Acceptance Criteria:

• Cache entry JSON
• Cache rendered HTML
• Cache graph data
• Cache search results (short TTL)
• Proper invalidation on updates
• Cache hit metrics

---

KNOW-028: Documentation

Priority: P1
Estimate: 4h
Labels: docs, phase-5

Description: Document the knowledge module.

Acceptance Criteria:

• User guide for knowledge module
• API reference (OpenAPI already in place)
• Wiki-link syntax reference
• Admin/config documentation
• Architecture overview for developers

---

Stretch Goals / Future

KNOW-029: Real-Time Collaboration

Priority: P3
Labels: future, collaboration

Description: Multiple users editing same entry simultaneously.

Notes:

• Would require CRDT or OT implementation
• Significant complexity
• Evaluate need before committing

---

KNOW-030: Entry Templates

Priority: P3
Labels: future, templates

Description: Pre-defined templates for common entry types.

Notes:

• ADR template
• Design doc template
• Meeting notes template
• Custom templates per workspace

---

KNOW-031: Attachments

Priority: P3
Labels: future, attachments

Description: Upload and embed images/files in entries.

Notes:

• S3/compatible storage backend
• Image optimization
• Paste images into editor

---

Summary

Phase	Issues	Est. Hours	Focus
1	KNOW-001 to KNOW-006	31h	CRUD + Basic UI
2	KNOW-007 to KNOW-012	24h	Wiki-links
3	KNOW-013 to KNOW-018	28h	Search
4	KNOW-019 to KNOW-022	19h	Graph
5	KNOW-023 to KNOW-028	25h	Polish
Total	28 issues	~127h	~3-4 dev weeks

---

Generated by Jarvis • 2025-01-29