From 8bd20ab4e645e4aa5b0c908aa14955354516071e Mon Sep 17 00:00:00 2001
From: Henry Li <henry1943@163.com>
Date: Fri, 6 Feb 2026 14:40:52 +0800
Subject: [PATCH] docs: add CLAUDE.md

---
 frontend/CLAUDE.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 frontend/CLAUDE.md

diff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.md
new file mode 100644
index 0000000..9057ad2
--- /dev/null
+++ b/frontend/CLAUDE.md
@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+DeerFlow Frontend is a Next.js 16 web interface for an AI agent system. It communicates with a LangGraph-based backend to provide thread-based AI conversations with streaming responses, artifacts, and a skills/tools system.
+
+**Stack**: Next.js 16, React 19, TypeScript 5.8, Tailwind CSS 4, pnpm 10.26.2
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `pnpm dev` | Dev server with Turbopack (http://localhost:3000) |
+| `pnpm build` | Production build |
+| `pnpm check` | Lint + type check (run before committing) |
+| `pnpm lint` | ESLint only |
+| `pnpm lint:fix` | ESLint with auto-fix |
+| `pnpm typecheck` | TypeScript type check (`tsc --noEmit`) |
+| `pnpm start` | Start production server |
+
+No test framework is configured.
+
+## Architecture
+
+```
+Frontend (Next.js) ──▶ LangGraph SDK ──▶ LangGraph Backend (lead_agent)
+                                              ├── Sub-Agents
+                                              └── Tools & Skills
+```
+
+The frontend is a stateful chat application. Users create **threads** (conversations), send messages, and receive streamed AI responses. The backend orchestrates agents that can produce **artifacts** (files/code), **todos**, and **citations**.
+
+### Source Layout (`src/`)
+
+- **`app/`** — Next.js App Router. Routes: `/` (landing), `/workspace/chats/[thread_id]` (chat).
+- **`components/`** — React components split into:
+  - `ui/` — Shadcn UI primitives (auto-generated, ESLint-ignored)
+  - `ai-elements/` — Vercel AI SDK elements (auto-generated, ESLint-ignored)
+  - `workspace/` — Chat page components (messages, artifacts, settings)
+  - `landing/` — Landing page sections
+- **`core/`** — Business logic, the heart of the app:
+  - `threads/` — Thread creation, streaming, state management (hooks + types)
+  - `api/` — LangGraph client singleton
+  - `artifacts/` — Artifact loading and caching
+  - `i18n/` — Internationalization (en-US, zh-CN)
+  - `settings/` — User preferences in localStorage
+  - `memory/` — Persistent user memory system
+  - `skills/` — Skills installation and management
+  - `messages/` — Message processing and transformation
+  - `mcp/` — Model Context Protocol integration
+  - `models/` — TypeScript types and data models
+- **`hooks/`** — Shared React hooks
+- **`lib/`** — Utilities (`cn()` from clsx + tailwind-merge)
+- **`server/`** — Server-side code (better-auth, not yet active)
+- **`styles/`** — Global CSS with Tailwind v4 `@import` syntax and CSS variables for theming
+
+### Data Flow
+
+1. User input → thread hooks (`core/threads/hooks.ts`) → LangGraph SDK streaming
+2. Stream events update thread state (messages, artifacts, todos)
+3. TanStack Query manages server state; localStorage stores user settings
+4. Components subscribe to thread state and render updates
+
+### Key Patterns
+
+- **Server Components by default**, `"use client"` only for interactive components
+- **Thread hooks** (`useThreadStream`, `useSubmitThread`, `useThreads`) are the primary API interface
+- **LangGraph client** is a singleton obtained via `getAPIClient()` in `core/api/`
+- **Environment validation** uses `@t3-oss/env-nextjs` with Zod schemas (`src/env.js`). Skip with `SKIP_ENV_VALIDATION=1`
+
+## Code Style
+
+- **Imports**: Enforced ordering (builtin → external → internal → parent → sibling), alphabetized, newlines between groups. Use inline type imports: `import { type Foo }`.
+- **Unused variables**: Prefix with `_`.
+- **Class names**: Use `cn()` from `@/lib/utils` for conditional Tailwind classes.
+- **Path alias**: `@/*` maps to `src/*`.
+- **Components**: `ui/` and `ai-elements/` are generated from registries (Shadcn, MagicUI, React Bits, Vercel AI SDK) — don't manually edit these.
+
+## Environment
+
+Backend API URLs are optional; an nginx proxy is used by default:
+```
+NEXT_PUBLIC_BACKEND_BASE_URL=http://localhost:8001
+NEXT_PUBLIC_LANGGRAPH_BASE_URL=http://localhost:2024
+```
+
+Requires Node.js 22+ and pnpm 10.26.2+.