knowledge-graph-agent/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a knowledge graph visualization system with a Go backend providing REST APIs and a React frontend using AntV G6 for interactive graph rendering. The system stores graph data in Neo4j and provides nodes, edges, and relationship visualization.

Architecture

Backend (/backend)

• Entry point: main.go - Sets up Gin router, initializes Neo4j connection, registers handlers
• Handlers (/handlers): HTTP request handlers for /api/graph, /api/search, /api/nodes/:id, /api/nodes/:id/neighbors
• Services (/services): Business logic layer. Neo4jService queries Neo4j and converts results to domain models
• Models (/models): Domain models (Node, Edge, GraphData) and API response types
• Neo4j client (/neo4j): Connection wrapper using github.com/neo4j/neo4j-go-driver/v5
• Config (/config): Configuration loading from .env with CORS and server settings

Important: Neo4j connection config is in backend/config/.env which contains credentials. The service queries Neo4j by executing Cypher queries and converting results to JSON.

Frontend (/frontend)

• React 19 + TypeScript + Vite build system
• State management: Zustand stores (graphStore.ts, layoutStore.ts)
• Graph visualization: AntV G6 v5 for force-directed layout and interactive graphs
• Styling: Tailwind CSS v4 + HeroUI components
• API client: Axios (services/graphApi.ts)

Key frontend components:

• KnowledgeGraph.tsx - Main page that wires up search, graph view, and node panel
• GraphView/index.tsx - G6 graph rendering with node selection, highlighting
• NodePanel/index.tsx - Sidebar showing selected node details
• SearchBar/index.tsx - Search input with node autocomplete

Common Commands

Backend

cd backend
go run main.go              # Start dev server on :3001
swag init -g main.go        # Regenerate Swagger docs

Frontend

cd frontend
npm run dev                 # Start dev server on :5173
npm run build               # Production build
npm run lint                # Lint code

API Endpoints

• GET /health - Health check
• GET /api/graph - Get all graph data (nodes + edges)
• GET /api/graph/stats - Graph statistics
• GET /api/search?q=query - Search nodes by label, ID, or type
• GET /api/nodes/:id - Get node by ID
• GET /api/nodes/:id/neighbors - Get node neighbors and related edges
• GET /swagger/* - Swagger UI documentation

Data Flow

1. Frontend fetches graph data via /api/graph
2. Graph data is stored in graphStore (Zustand)
3. GraphView renders with G6 force-directed layout
4. Node clicks highlight connected nodes and trigger NodePanel updates
5. Search queries /api/search and selects matching nodes

Neo4j Queries

The backend uses these Cypher query patterns:

• All nodes: MATCH (n) RETURN n
• All edges: MATCH (a)-[r]->(b) RETURN a.id AS source, b.id AS target, r
• Node by ID: MATCH (n {id: $id}) RETURN n
• Search: MATCH (n) WHERE toLower(n.label) CONTAINS toLower($query) OR ... RETURN n
• Neighbors: MATCH ({id: $id})-[r]-(m) RETURN m, r, startNode(r).id AS source, endNode(r).id AS target

File Conventions

• Backend handlers follow *_handler.go naming
• Swagger annotations in handlers with @Summary, @Router, etc.
• Frontend types in types/graph.ts shared between components
• Graph styling utilities in utils/graphStyle.ts