agent-park/AGENTS.md

PROJECT KNOWLEDGE BASE

Generated: 2026-02-01 Commit: N/A (new generation) Branch: main

OVERVIEW

Next.js 15 multilingual AI project navigation website with App Router, TypeScript, Prisma ORM, and Tailwind CSS neo-brutalism design. Features automated project discovery and quarterly AI keyword cloud system.

STRUCTURE

agent_park/
├── src/
│   ├── app/                    # Next.js App Router (locale-prefixed routes)
│   │   ├── [locale]/         # Internationalized routes (zh/en)
│   │   │   ├── projects/     # Project listing and details
│   │   │   ├── keyword-cloud/ # Quarterly AI trends
│   │   │   └── layout.tsx   # Header/footer/Announcement
│   │   ├── api/               # API routes (no locale prefix)
│   │   │   ├── webhook/      # Project ingestion
│   │   │   ├── discovery/     # Automated exploration tasks
│   │   │   ├── search/       # AI-powered search
│   │   │   └── keyword-cloud/ # Keywords API
│   │   ├── components/         # React components (organized by domain)
│   │   ├── lib/              # Validation, utilities, Prisma client
│   │   ├── hooks/            # Server-side data fetching
│   │   └── i18n/             # next-intl configuration
│   └── layout.tsx            # Root layout (locale default: zh)
├── prisma/
│   └── schema.prisma          # Database models (multilingual support)
├── .claude/
│   ├── agents/                # Custom Claude agents
│   └── commands/              # Claude commands
├── scripts/                   # Seed/test scripts
├── public/                    # Static assets
└── CLAUDE.md                 # This file (existing)

WHERE TO LOOK

Task	Location	Notes
Add new page	src/app/[locale]/	Follow locale routing pattern
Create API endpoint	src/app/api/	Use crypto.timingSafeEqual() for auth
Add component	src/components/	Neo-brutalism: 0px radius, bold borders
Database migration	prisma/schema.prisma	Run pnpm prisma migrate dev after changes
Add validation	src/lib/validations.ts	Follow existing Zod schema patterns
Fetch data	src/hooks/	Server functions, NOT React hooks
Webhook	src/app/api/webhook/	Multi-level deduplication strategy
Discovery task	src/app/api/discovery/	Task management API
i18n messages	src/messages/	Update BOTH zh.json AND en.json

CODE MAP

Main Entry Points:
├── src/app/[locale]/layout.tsx    → Root layout (header/footer)
├── src/app/[locale]/page.tsx       → Home page (ISR 5min)
├── src/app/layout.tsx              → Root layout (fonts, locale)
└── src/middleware.ts                → Locale detection (next-intl)

Data Layer:
├── src/hooks/useProjects.ts           → Projects/tags/search
├── src/hooks/useKeywordCloud.ts      → Keywords/quarters/rules
└── src/lib/prisma.ts                → Prisma client singleton

API Routes:
├── src/app/api/webhook/projects/route.ts      → Project ingestion
├── src/app/api/discovery/tasks/route.ts       → Task CRUD
├── src/app/api/search/ai/route.ts            → AI search
└── src/app/api/keyword-cloud/[...]/route.ts  → Keywords API

Complex Components:
├── src/components/project/MarkdownContent.tsx (269 lines) → Markdown renderer
├── src/app/api/discovery/lib/discovery-service.ts      → Deduplication logic
└── src/app/api/webhook/projects/route.ts      → Webhook handler

CONVENTIONS

Multilingual Architecture

• Default locale: Chinese (zh), not English
• Route pattern: /{locale}/path (locale prefix ALWAYS required)
• Field naming: Dual-language pairs (name/nameEn, description/descriptionEn)
• Content selection: locale === 'en' && fieldEn ? fieldEn : field
• Translation files: Update BOTH src/messages/zh.json AND src/messages/en.json

Type Safety

• Strict mode: Enabled with noUncheckedIndexedAccess, noImplicitReturns, noFallthroughCasesInSwitch
• Path aliases: @/* maps to ./src/*
• Validation: All API inputs via Zod schemas in src/lib/validations.ts

Database Patterns

• Multi-level deduplication: GitHub URL → Website URL → slug match (highest → lowest priority)
• Cascade deletion: ExternalLink and ProjectTag auto-delete on project delete
• Composite indexes: Optimized for frequent queries (status+createdAt, type+url)
• Constraints: Project.slug unique, Tag.name unique, ExternalLink(projectId, url) unique

API Authentication

• Method: crypto.timingSafeEqual() for timing-safe comparison (prevents timing attacks)
• Key location: Request body (NOT headers)
• Validation: WEBHOOK_API_KEY (32+ chars)

Design System (Neo-Brutalism)

• Corners: 0px radius (sharp)
• Shadows: 4px solid borders (shadow-neo class)
• Colors: Primary gold (#FFD700), secondary orange (#ff6f00)
• Typography: Space Mono (headings), Inter (body)
• Dark mode: Class-based with dark: prefix

Git Commits

• Format: <type>: <description> (Chinese lowercase types)
• Types: feat (新功能), fix (修复), refactor (重构), chore (杂项)
• Examples:
  • feat: 新增项目发现任务系统
  • fix: 修复 ESLint 错误

ANTI-PATTERNS (THIS PROJECT)

Environment Variables

• NEVER use vercel.json for env vars (use Vercel Dashboard)
• NEVER commit .env.local files or environment variables
• ALWAYS verify API responses with WEBHOOK_API_KEY when testing endpoints

Database Operations

• NEVER modify schema without running migrations
• ALWAYS run pnpm prisma migrate dev --name <migration_name> after schema changes
• ALWAYS run pnpm prisma generate after migrations

Development Workflow

• NEVER skip pre-commit hooks (no --no-verify, --no-gpg-sign flags)
• NEVER commit unless explicitly requested by orchestrator
• ALWAYS run pnpm build before committing
• MUST use chrome-devtools-mcp to verify frontend changes

Content Standards

• NEVER include dynamic data (star/fork counts) in project content
• ALWAYS use GitHub Badge for dynamic stats
• NEVER use mechanical translation - write naturally for each locale
• ALWAYS avoid marketing terminology in descriptions

Security

• NEVER use string comparison for API keys (timing attacks)
• ALWAYS use crypto.timingSafeEqual() for authentication
• ALWAYS validate inputs with Zod schemas
• NEVER log raw API keys or sensitive data

UNIQUE STYLES

Project Discovery System

• Architecture: Dual-agent system (content-explorer-agent + api-submitter-agent)
• Workflow: URL input → PENDING tasks → batch processing → COMPLETED/FAILED
• Deduplication: Multi-level strategy (GitHub → Website → slug)
• Retry logic: Exponential backoff, max 3 attempts
• Environment: WEBHOOK_API_KEY required for submitter agent
• See: src/app/AGENTS.md for app-specific patterns

Keyword Cloud System

• Workflow: n8n automation → API → PostgreSQL → Next.js
• Data: Quarterly snapshots with visual style rules
• API: Rate-limited, requires API key
• Error logging: KeywordCloudErrorLog table
• See: src/app/AGENTS.md for app-specific patterns

Component System

• Design: Neo-brutalism with 0px corners, 4px solid borders, gold/orange theme
• Organization: layout/locale/project/search/ui (4 domains), project/ (11 files, highest)
• Largest component: MarkdownContent.tsx (269 lines) with complex react-markdown overrides
• See: src/components/AGENTS.md for component-specific patterns

Data Access Layer

• Validation: Centralized Zod schemas in src/lib/validations.ts
• Utilities: Class merging (cn()), slug generation, Prisma client singleton
• GitHub integration: Badge-based approach, cached API stats (5min)
• See: src/lib/AGENTS.md for library patterns

Server-Side Hooks

• Purpose: Server functions for data fetching, NOT React hooks
• Query optimization: N+1 prevention, selective loading, index utilization
• ISR strategy: 5-minute revalidation on project details
• See: src/hooks/AGENTS.md for data fetching patterns

COMMANDS

pnpm dev          # Start dev server (Next.js 15)
pnpm build        # Production build
pnpm start        # Start production server
pnpm lint         # ESLint check
pnpm test         # Vitest unit tests
pnpm test:e2e     # Playwright E2E tests
pnpm prisma migrate dev   # Run migrations
pnpm prisma db seed       # Seed database
pnpm prisma studio        # Database inspector

NOTES

Project Discovery Gotchas

• Tag upsert follows: 1) Find by name, 2) Try upsert by slug, 3) Use existing if slug conflicts
• Webhook updates ALL project fields, replaces ALL tags/links (no partial updates)
• Deduplication logic in src/app/api/discovery/lib/discovery-service.ts:16-80

i18n Gotchas

• Missing translation keys display as missing_key_name in UI
• All new UI text requires BOTH zh.json AND en.json updates
• Test both locales: /{zh}/path and /{en}/path

Database Gotchas

• Project.slug globally unique - use existing project if slug conflicts
• Tag.name globally unique - upsert handles conflicts via slug fallback
• Run pnpm prisma studio to inspect state during development

Performance Considerations

• ISR: Project detail pages revalidate every 5 minutes (revalidate = 300)
• Indexes: Composite on (status, createdAt), (type, url) for optimized queries
• N+1 prevention: Batch tag queries in webhook (useProjects.ts)

Missing CI/CD

• No GitHub Actions workflows (rely on Vercel deployment)
• No automated testing in CI pipeline
• Test frameworks configured (Vitest, Playwright) but not extensively used

LSP Errors

• Missing Prisma models in src/hooks/useKeywordCloud.ts and scripts/seed-keyword-cloud.ts:
  • Run pnpm prisma migrate dev to generate keyword cloud tables
  • Models: Quarter, Keyword, VisualStyleRule, keywordCloudErrorLog

Subdirectories

• src/app/: App Router architecture, locale routing, API structure (see src/app/AGENTS.md)
• src/components/: Neo-brutalism design system, component organization (see src/components/AGENTS.md)
• src/lib/: Validation layer, utilities, GitHub integration (see src/lib/AGENTS.md)
• src/hooks/: Server-side data fetching, query optimization (see src/hooks/AGENTS.md)