stack/docs/scratchpads/71-graph-data-api.md

Issue #71: [KNOW-019] Graph Data API

Objective

Create API endpoints to retrieve knowledge graph data for visualization, including nodes (entries) and edges (relationships) with filtering and statistics capabilities.

Approach

1. Review existing knowledge schema and relationships table
2. Define DTOs for graph data structures (nodes, edges, filters)
3. Write tests for graph endpoints (TDD approach)
4. Implement GraphService for data aggregation and processing
5. Create graph controller with three endpoints
6. Implement orphan detection, filtering, and node limiting
7. Test with sample data
8. Run quality checks and commit

Progress

• Review schema and existing code
• Define DTOs for graph structures
• Write tests for graph endpoints (RED)
• Implement GraphService (GREEN)
• Create graph controller endpoints (GREEN)
• Implement orphan detection
• Add filtering capabilities
• Add node count limiting
• Run code review
• Run QA checks
• Commit changes
• Close issue

Completion Summary

Issue #71 has been successfully completed with all acceptance criteria met:

1. GET /api/knowledge/graph - Full knowledge graph endpoint implemented

   • Returns all entries and links with optional filtering
   • Supports filtering by tags, status
   • Includes node count limit option
   • Orphan detection included

2. GET /api/knowledge/graph/:slug - Entry-centered subgraph endpoint implemented

   • Returns subgraph centered on specific entry
   • Supports depth parameter (1-5, default 1)
   • Uses BFS traversal for connected nodes

3. GET /api/knowledge/graph/stats - Graph statistics endpoint implemented

   • Returns total entries and links
   • Detects and counts orphan entries
   • Calculates average links per entry
   • Shows top 10 most connected entries
   • Provides tag distribution

All tests passing (21 tests), code quality gates passed, and changes committed to develop branch.

API Endpoints

1. GET /api/knowledge/graph - Return full knowledge graph with filters
2. GET /api/knowledge/graph/:slug - Return subgraph centered on entry
3. GET /api/knowledge/graph/stats - Return graph statistics

Graph Data Format

{
  nodes: [
    {
      id: string,
      slug: string,
      title: string,
      type: string,
      status: string,
      tags: string[],
      isOrphan: boolean
    }
  ],
  edges: [
    {
      source: string,  // node id
      target: string,  // node id
      type: string     // relationship type
    }
  ]
}

Testing

• Unit tests for GraphService methods
• Integration tests for graph endpoints
• Test filtering, orphan detection, and node limiting
• Verify graph statistics calculation

Notes

Existing Code Analysis

• GraphService already exists with getEntryGraph() method for entry-centered graphs
• GraphNode and GraphEdge interfaces defined in entities/graph.entity.ts
• GraphQueryDto exists but only for entry-centered view (depth parameter)
• KnowledgeLinks table connects entries (source_id, target_id, resolved flag)
• No full graph endpoint exists yet
• No orphan detection implemented yet
• No graph statistics endpoint yet

Implementation Plan

1. Create new graph.controller.ts for graph endpoints
2. Extend GraphService with:
   • getFullGraph(workspaceId, filters) - full graph with optional filters
   • getGraphStats(workspaceId) - graph statistics including orphan detection
3. Create new DTOs:
   • GraphFilterDto - for filtering by tags, status, limit
   • GraphStatsResponse - for statistics response
   • FullGraphResponse - for full graph response
4. Add tests for new service methods (TDD)
5. Wire up controller to module

Implementation Summary

Files Created:

• /apps/api/src/knowledge/graph.controller.ts - New controller with 3 endpoints
• /apps/api/src/knowledge/graph.controller.spec.ts - Controller tests (7 tests, all passing)

Files Modified:

• /apps/api/src/knowledge/dto/graph-query.dto.ts - Added GraphFilterDto
• /apps/api/src/knowledge/entities/graph.entity.ts - Extended interfaces with isOrphan, status fields, added FullGraphResponse and GraphStatsResponse
• /apps/api/src/knowledge/services/graph.service.ts - Added getFullGraph(), getGraphStats(), getEntryGraphBySlug()
• /apps/api/src/knowledge/services/graph.service.spec.ts - Added 7 new tests (14 total, all passing)
• /apps/api/src/knowledge/knowledge.module.ts - Registered KnowledgeGraphController
• /apps/api/src/knowledge/dto/index.ts - Exported GraphFilterDto

API Endpoints Implemented:

1. GET /api/knowledge/graph - Returns full knowledge graph

   • Query params: tags[], status, limit
   • Returns: nodes[], edges[], stats (totalNodes, totalEdges, orphanCount)

2. GET /api/knowledge/graph/stats - Returns graph statistics

   • Returns: totalEntries, totalLinks, orphanEntries, averageLinks, mostConnectedEntries[], tagDistribution[]

3. GET /api/knowledge/graph/:slug - Returns entry-centered subgraph

   • Query params: depth (1-5, default 1)
   • Returns: centerNode, nodes[], edges[], stats

Key Features:

• Orphan detection: Identifies entries with no incoming or outgoing links
• Filtering: By tags, status, and node count limit
• Performance optimizations: Uses raw SQL for aggregate queries
• Tag distribution: Shows entry count per tag
• Most connected entries: Top 10 entries by link count
• Caching: Leverages existing cache service for entry-centered graphs

Test Coverage:

• 21 total tests across service and controller
• All tests passing
• Coverage includes orphan detection, filtering, statistics calculation