stack/docs/MINDMAP_API_INTEGRATION.md

Mindmap API Integration

Overview

The mindmap components have been successfully wired to the Knowledge module API. The integration transforms Knowledge entries into graph nodes and uses backlinks to build edges.

API Endpoints Used

Node Operations (Knowledge Entries)

• GET /api/knowledge/entries - Fetch all entries (transformed to nodes)
• POST /api/knowledge/entries - Create new entry (node)
• PUT /api/knowledge/entries/:slug - Update entry (node)
• DELETE /api/knowledge/entries/:slug - Delete entry (node)

Edge Operations (Backlinks)

• GET /api/knowledge/entries/:slug/backlinks - Get relationships (edges)
• Edge creation: Adds wiki-links to source entry content ([[slug|title]])
• Edge deletion: Removes wiki-links from source entry content

Search

• GET /api/knowledge/search?q=query - Full-text search across entries

Data Transformations

Entry → Node

{
  id: entry.id,
  title: entry.title,
  node_type: entry.tags[0]?.slug || 'concept',
  content: entry.content || entry.summary,
  tags: entry.tags.map(t => t.slug),
  domain: entry.tags[0]?.name,
  metadata: { slug, status, visibility, createdBy, updatedBy },
  created_at: entry.createdAt,
  updated_at: entry.updatedAt
}

Node → Entry

{
  title: node.title,
  content: node.content,
  summary: node.content?.slice(0, 200),
  tags: node.tags.length > 0 ? node.tags : [node.node_type],
  status: 'PUBLISHED',
  visibility: 'WORKSPACE'
}

Backlinks → Edges

• Backlinks are automatically created when wiki-links exist in entry content
• Format: [[target-slug|Display Text]]
• Edges use relates_to as the default relation type

Features Implemented

1. Graph Data Fetching

• ✅ Fetches all entries from /api/knowledge/entries
• ✅ Transforms entries to graph nodes
• ✅ Fetches backlinks for each entry to build edges
• ✅ Handles pagination (limit: 100 entries)

2. CRUD Operations

• ✅ Create node → POST to /api/knowledge/entries
• ✅ Update node → PUT to /api/knowledge/entries/:slug
• ✅ Delete node → DELETE to /api/knowledge/entries/:slug
• ✅ Auto-refresh graph after mutations

3. Edge Management

• ✅ Create edge → Inserts wiki-link in source content
• ✅ Delete edge → Removes wiki-link from source content
• ✅ Auto-refresh graph after mutations

4. Search Integration

• ✅ Real-time search using /api/knowledge/search
• ✅ Search results dropdown with node selection
• ✅ Loading indicator during search

5. Real-time Updates

• ✅ Graph automatically refetches after create/update/delete
• ✅ Statistics recalculate when graph changes
• ✅ UI updates reflect backend state

Component Structure

useGraphData Hook

Location: apps/web/src/components/mindmap/hooks/useGraphData.ts

Provides:

• graph: GraphData object (nodes + edges)
• isLoading: Loading state
• error: Error messages
• fetchGraph(): Refresh graph data
• createNode(): Create new node
• updateNode(): Update existing node
• deleteNode(): Delete node
• createEdge(): Create edge (adds wiki-link)
• deleteEdge(): Delete edge (removes wiki-link)
• searchNodes(): Search for nodes
• fetchMermaid(): Generate Mermaid diagram
• statistics: Graph statistics

MindmapViewer Component

Location: apps/web/src/components/mindmap/MindmapViewer.tsx

Features:

• Interactive graph view (ReactFlow)
• Mermaid diagram view
• Search bar with live results
• Node creation modal
• Node details panel
• CRUD operations toolbar
• Statistics display

ReactFlowEditor Component

Location: apps/web/src/components/mindmap/ReactFlowEditor.tsx

Features:

• Visual graph rendering
• Drag-and-drop nodes
• Click to connect edges
• Node selection and deletion
• Mini-map navigation
• Background grid

Testing Checklist

• Graph loads with real data from Knowledge API
• Create node operation works
• Update node operation works
• Delete node operation works
• Create edge adds wiki-link
• Delete edge removes wiki-link
• Search returns results
• Graph updates in real-time after mutations
• TypeScript compiles without errors
• No console errors during operation

Known Limitations

1. Edge Type: All edges use relates_to relation type by default
2. Pagination: Limited to 100 entries per fetch
3. Wiki-links: Edges are created via wiki-links, which may result in content modifications
4. Slug-based: Update/delete operations require looking up the node's slug from metadata

Future Enhancements

1. Support multiple edge types (depends_on, part_of, etc.)
2. Implement pagination for large graphs
3. Add filtering by node type
4. Add graph layout algorithms
5. Support for direct edge creation without wiki-links
6. Real-time collaborative editing with WebSockets