83 lines
3.5 KiB
Markdown
83 lines
3.5 KiB
Markdown
|
# 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
|
||
|
|
```bash
|
||
|
|
cd backend
|
||
|
|
go run main.go # Start dev server on :3001
|
||
|
|
swag init -g main.go # Regenerate Swagger docs
|
||
|
|
```
|
||
|
|
|
||
|
|
### Frontend
|
||
|
|
```bash
|
||
|
|
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`
|