Claude-Code-Workflow/ccw/src/core/routes/graph-routes.md

Graph Routes API Documentation

Overview

The Graph Routes module provides REST API endpoints for querying and visualizing code structure data from CodexLens indices. It exposes symbols and their relationships as graph nodes and edges.

Endpoints

GET /api/graph/nodes

Query all symbols from the CodexLens SQLite database and return them as graph nodes.

Query Parameters:

• path (optional): Project path. Defaults to server's initial path.

Response:

{
  "nodes": [
    {
      "id": "src/file.ts:functionName:10",
      "name": "functionName",
      "type": "FUNCTION",
      "file": "src/file.ts",
      "line": 10
    }
  ]
}

Node Types:

• FUNCTION: Functions and procedures
• CLASS: Classes, interfaces, and type definitions
• METHOD: Class methods
• VARIABLE: Variables and constants
• MODULE: Module-level definitions

---

GET /api/graph/edges

Query all code relationships from the CodexLens SQLite database and return them as graph edges.

Query Parameters:

• path (optional): Project path. Defaults to server's initial path.

Response:

{
  "edges": [
    {
      "source": "src/file.ts:caller:10",
      "target": "module.callee",
      "type": "CALLS",
      "sourceLine": 10,
      "sourceFile": "src/file.ts"
    }
  ]
}

Edge Types:

• CALLS: Function/method invocations
• IMPORTS: Import/require relationships
• INHERITS: Class inheritance

---

GET /api/graph/impact

Get impact analysis for a symbol - determines what code is affected if this symbol changes.

Query Parameters:

• path (optional): Project path. Defaults to server's initial path.
• symbol (required): Symbol ID in format file:name:line

Response:

{
  "directDependents": [
    "src/other.ts:caller:20",
    "src/another.ts:user:35"
  ],
  "affectedFiles": [
    "src/other.ts",
    "src/another.ts"
  ]
}

---

Implementation Details

PathMapper

Maps source code paths to CodexLens index database paths following the storage structure:

• Windows: D:\path\to\project → ~/.codexlens/indexes/D/path/to/project/_index.db
• Unix: /home/user/project → ~/.codexlens/indexes/home/user/project/_index.db

Database Schema

Queries two main tables:

1. symbols - Code symbol definitions
   • id, file_id, name, kind, start_line, end_line
2. code_relationships - Inter-symbol dependencies
   • id, source_symbol_id, target_qualified_name, relationship_type, source_line, target_file

Error Handling

• Returns empty arrays ([]) if index database doesn't exist
• Returns 500 with error message on database query failures
• Returns 400 if required parameters are missing

Type Mappings

Symbol Kinds → Node Types:

{
  'function' → 'FUNCTION',
  'class' → 'CLASS',
  'method' → 'METHOD',
  'variable' → 'VARIABLE',
  'module' → 'MODULE',
  'interface' → 'CLASS',
  'type' → 'CLASS'
}

Relationship Types → Edge Types:

{
  'call' → 'CALLS',
  'import' → 'IMPORTS',
  'inherits' → 'INHERITS',
  'uses' → 'CALLS'
}

---

Usage Examples

Fetch All Nodes

curl "http://localhost:3000/api/graph/nodes?path=/path/to/project"

Fetch All Edges

curl "http://localhost:3000/api/graph/edges?path=/path/to/project"

Analyze Impact

curl "http://localhost:3000/api/graph/impact?path=/path/to/project&symbol=src/file.ts:functionName:10"

---

Integration with CodexLens

This module requires:

1. CodexLens to be installed and initialized (/api/codexlens/init)
2. Project to be indexed (creates _index.db files)
3. better-sqlite3 package for direct database access

Dependencies

• better-sqlite3: Direct SQLite database access
• codex-lens: Python package providing the indexing infrastructure
• path, fs, os: Node.js built-in modules for file system operations