From 3ff8f3951abf03501d37826ae7ac712c74c8abd9 Mon Sep 17 00:00:00 2001 From: wonder Date: Tue, 28 Apr 2026 12:44:08 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=E6=9E=B6=E6=9E=84?= =?UTF-8?q?=E5=9B=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 82 ---------------------------------------- project-architecture.svg | 80 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+), 82 deletions(-) delete mode 100644 CLAUDE.md create mode 100644 project-architecture.svg diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index b940fc2..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,82 +0,0 @@ -# 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` diff --git a/project-architecture.svg b/project-architecture.svg new file mode 100644 index 0000000..42407b0 --- /dev/null +++ b/project-architecture.svg @@ -0,0 +1,80 @@ + + + + + + + + + + + + knowledge-graph-agent 项目架构图 + 知识图谱 + 层级记忆 + 自省反馈 + AI 对话 + 邮件自动化 + + 用户交互层 + + 应用服务层 + + 数据与外部能力层 + + React 前端 + Graph UI / Chat UI + + AntV G6 + Zustand + 图谱渲染 / 状态管理 + + Axios + Tailwind + API 请求 / UI 样式 + + Gin API 层 + REST 接口 / 路由 / 校验 + + Graph Service + 查询 / 搜索 / 邻居 / CRUD + + AI ＆ Conversation + Prompt / 会话 / 上下文增强 + + Neo4j 5.x + 知识图谱持久化 + + AI Provider + 硅基流动 OpenAI 接口 + + 邮件自动化 + 后续增强 + + + 用户操作 / 查询 + + + 图谱浏览 / 编辑 + + + 提交消息 / 交互 + + + 读写图数据 + + + 检索上下文 / 记忆 + + + 生成回复 / 调用模型 + + + 定时任务 / 邮件 + + + 主要请求 / 数据流 + + + 外部能力 / 触发流 + \ No newline at end of file