agent-park/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Build & Run

pnpm dev          # Start development server (Next.js 15)
pnpm build        # Build for production
pnpm start        # Start production server
pnpm lint         # Run ESLint

Testing

pnpm test         # Run Vitest unit tests
pnpm test:e2e     # Run Playwright E2E tests

Database

pnpm prisma migrate dev   # Run database migrations
pnpm prisma migrate dev --name init    # Create initial migration
pnpm prisma db seed       # Seed database (uses ts-node)
pnpm prisma studio        # Open Prisma Studio for database inspection

Architecture Overview

This is a Next.js 15 multilingual AI project navigation website using the App Router architecture with the following key components:

i18n Architecture (next-intl)

• Locales: zh (default) and en
• Route pattern: /{locale}/path (always prefixed with locale)
• Middleware: src/middleware.ts handles locale detection and routing
• i18n config: src/i18n/request.ts loads locale messages from src/messages/{locale}.json
• Messages: Translation files at src/messages/zh.json and src/messages/en.json

App Router Structure

src/app/
├── [locale]/           # Locale-scoped routes
│   ├── page.tsx        # Home page
│   ├── projects/       # Projects listing and details
│   │   ├── page.tsx    # Projects list
│   │   └── [id]/       # Individual project details (slug-based)
│   └── layout.tsx      # Locale layout (header, footer)
├── api/                # API routes (no locale prefix)
│   └── webhook/projects/route.ts  # Webhook for project ingestion
└── layout.tsx          # Root layout

Database (Prisma + PostgreSQL)

• Schema: prisma/schema.prisma defines models: Project, Tag, ExternalLink
• Enums: ProjectStatus (ACTIVE/ARCHIVED), LinkType (WEBSITE/GITHUB/HUGGINGFACE/PAPER)
• Client singleton: src/lib/prisma.ts exports Prisma client instance
• Multilingual fields: Most models have name/nameEn, description/descriptionEn, content/contentEn pairs
• Indexes: idx_project_status_createdAt, idx_project_slug, idx_tag_slug, idx_link_projectId, idx_link_type

Webhook Deduplication Strategy

The webhook at src/app/api/webhook/projects/route.ts implements a multi-level deduplication strategy to prevent duplicate projects:

1. GitHub URL exact match (highest priority) - via ExternalLink table
2. Website URL exact match - via ExternalLink table
3. slug match (fallback) - via Project.slug field

When updating an existing project, the webhook:

• Updates all project fields (name, description, content, status, source)
• Replaces all tags (deletes old connections, creates new ones)
• Replaces all links (deletes old links, creates new ones)

Data Fetching (Server-Side)

• Location: src/hooks/useProjects.ts (server functions, not React hooks)
• Functions: getProjects(), getProjectBySlug(), getAllTags(), getTagsWithProjectCounts()
• Usage: Directly called in Server Components and route handlers
• ISR: Project detail pages use export const revalidate = 300 (5 minutes)

Validation (Zod)

• Schemas: src/lib/validations.ts defines all Zod schemas
• ProjectInputSchema: Validates incoming project data (1-10 tags, 1-10 links required)
• WebhookPayloadSchema: Validates webhook requests with API key (1-100 projects per request)
• ProjectQuerySchema: Validates query parameters (search, tags, status, page, limit)

Styling (Tailwind CSS)

• Neo-brutalism design: Sharp corners (0px radius), bold borders (4px shadows), hard edges
• Theme colors:
  • Primary: Gold (#FFD700)
  • Secondary: Orange (#ff6f00)
  • Background light: #F5F2EB, dark: #121212
  • Surface light: #FFFFFF, dark: #1E1E1E
• Typography: Space Mono (headings), Inter (body)
• Dark mode: Class-based with dark: prefix
• Config: tailwind.config.ts extends theme with custom colors, shadows, and animations

Content Rendering

• Markdown: Project content fields support Markdown via react-markdown
• Plugins: rehype-raw, rehype-sanitize, rehype-shiki, remark-gfm
• Usage: ProjectDetail component renders content/contentEn as Markdown

UI Components

• Radix UI primitives: @radix-ui/react-slot, @radix-ui/react-navigation-menu, @radix-ui/react-dropdown-menu, @radix-ui/react-separator
• Lucide React icons: Used throughout the app (package imports optimized via experimental.optimizePackageImports)
• Custom components: src/components/ organized by domain
  • layout/: Header, Footer
  • locale/: LocaleSwitcher
  • project/: ProjectCard, ProjectList, ProjectDetail, ProjectSidebar, RelatedProjects, TagCloud, ExternalLinkCard
  • search/: SearchBar
  • ui/: Base UI components (buttons, cards, etc.)

Next.js Configuration

• next.config.js:
  • next-intl plugin wrapper for i18n
  • Image domains: localhost, *.anthropic.com
  • Lucide-react package import optimization
• tsconfig.json: ES2022 target, strict mode enabled

MCP Servers Usage (按需使用)

1. context7: 不确定 API 用法时查阅最新文档
2. chrome-devtools-mcp: 查看页面效果、调试 UI 修复 BUG
3. dbhub mcp: 查询数据库数据（PostgreSQL）
4. shadcn mcp: 确认 shadcn/ui 组件用法
5. web-search-prime: 默认联网搜索工具
6. vision-mcp-server: 图片/视频理解

Git Commits

提交信息主要使用中文，使用描述性的提交格式。

如果你需要查看页面 请不要直接启动项目 而是应该先检查是否已经有启动好的项目在localhost:3000运行。如果有的话请直接访问，如果没有的话再执行相关命令启动项目。