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

```typescript
{
  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

```typescript
{
  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

- [x] Graph loads with real data from Knowledge API
- [x] Create node operation works
- [x] Update node operation works
- [x] Delete node operation works
- [x] Create edge adds wiki-link
- [x] Delete edge removes wiki-link
- [x] Search returns results
- [x] Graph updates in real-time after mutations
- [x] TypeScript compiles without errors
- [x] 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