deer-flow/frontend/AGENTS.md

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Codex, and others) when working with the DeerFlow frontend. It is the source of truth; the sibling CLAUDE.md imports it via @AGENTS.md.

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. Requires Node.js 22+ and pnpm 10.26.2+.

Core dependencies

• LangGraph SDK (@langchain/langgraph-sdk ^1.5.3) — Agent orchestration and streaming
• LangChain Core (@langchain/core ^1.1.15) — Fundamental AI building blocks
• TanStack Query (@tanstack/react-query ^5.90.17) — Server state management
• UI: Shadcn UI, MagicUI, React Bits, and Vercel AI SDK elements (generated from registries — see Code Style)

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 format	Prettier check (pnpm format:write to apply)
pnpm test	Run unit tests with Rstest
pnpm test:e2e	Run E2E tests with Playwright (Chromium)
pnpm typecheck	TypeScript type check (tsc --noEmit)
pnpm start	Start production server

Unit tests live under tests/unit/ and mirror the src/ layout (e.g., tests/unit/core/api/stream-mode.test.ts tests src/core/api/stream-mode.ts). Powered by Rstest; import source modules via the @/ path alias.

E2E tests live under tests/e2e/ and use Playwright with Chromium. They mock all backend APIs via page.route() network interception and test real page interactions (navigation, chat input, streaming responses). Config: playwright.config.ts.

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) and todos.

Source Layout (src/)

• app/ — Next.js App Router. Routes include / (landing), /workspace/chats/[thread_id] (chat), /workspace/agents/[agent_name] and /workspace/agents/new (custom agents), /blog/…, the (auth)/{login,setup,auth/callback} flow, /[lang]/docs/…, and /api/… route handlers (e.g. /api/memory).
• components/ — React components:
  • 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
  • docs/ — Docs / MDX rendering components
• core/ — Business logic, the heart of the app. Domains include threads/ (creation, streaming, state), api/ (LangGraph client singleton), agents/ (custom agents), auth/ (authentication), artifacts/, channels/ (IM connections), i18n/ (en-US, zh-CN), settings/, memory/, skills/, messages/, mcp/, models/, suggestions/, tasks/, todos/, tools/, config/, notification/, blog/, plus rendering helpers (rehype/, streamdown/) and utils/.
• hooks/ — Shared React hooks
• lib/ — Utilities (cn() from clsx + tailwind-merge)
• content/ — MDX content (blog posts, docs) rendered by the app
• styles/ — Global CSS with Tailwind v4 @import syntax and CSS variables for theming
• typings/ — Ambient TypeScript declarations
• Root files: env.js (env validation), mdx-components.ts (MDX component map)

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

Interaction Ownership

• src/app/workspace/chats/[thread_id]/page.tsx owns composer busy-state wiring.
• src/core/threads/hooks.ts owns pre-submit upload state and thread submission.

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:8001/api

Leave these unset for the standard make dev / Docker flow, where nginx serves the public /api/langgraph/* prefix and rewrites it to Gateway's native /api/* routes.

Resources

• LangGraph Documentation
• LangChain Core Concepts
• TanStack Query Documentation
• Next.js App Router

Contributing

When adding features:

1. Follow the established src/ structure
2. Add TypeScript types and proper error handling
3. Write unit tests under tests/unit/ (pnpm test) and E2E tests under tests/e2e/ (pnpm test:e2e)
4. Run pnpm check before committing
5. Update this AGENTS.md when architecture, commands, or conventions change