# 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`