|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +FastGPT is an AI Agent construction platform providing out-of-the-box data processing, model invocation capabilities, and visual workflow orchestration through Flow. This is a full-stack TypeScript application built on NextJS with MongoDB/PostgreSQL backends. |
| 8 | + |
| 9 | +**Tech Stack**: NextJS + TypeScript + ChakraUI + MongoDB + PostgreSQL (PG Vector)/Milvus |
| 10 | + |
| 11 | +## Architecture |
| 12 | + |
| 13 | +This is a monorepo using pnpm workspaces with the following key structure: |
| 14 | + |
| 15 | +### Packages (Library Code) |
| 16 | +- `packages/global/` - Shared types, constants, utilities used across all projects |
| 17 | +- `packages/service/` - Backend services, database schemas, API controllers, workflow engine |
| 18 | +- `packages/web/` - Shared frontend components, hooks, styles, i18n |
| 19 | +- `packages/templates/` - Application templates for the template market |
| 20 | + |
| 21 | +### Projects (Applications) |
| 22 | +- `projects/app/` - Main NextJS web application (frontend + API routes) |
| 23 | +- `projects/sandbox/` - NestJS code execution sandbox service |
| 24 | +- `projects/mcp_server/` - Model Context Protocol server implementation |
| 25 | + |
| 26 | +### Key Directories |
| 27 | +- `document/` - Documentation site (NextJS app with content) |
| 28 | +- `plugins/` - External plugins (models, crawlers, etc.) |
| 29 | +- `deploy/` - Docker and Helm deployment configurations |
| 30 | +- `test/` - Centralized test files and utilities |
| 31 | + |
| 32 | +## Development Commands |
| 33 | + |
| 34 | +### Main Commands (run from project root) |
| 35 | +- `pnpm dev` - Start development for all projects (uses package.json workspace scripts) |
| 36 | +- `pnpm build` - Build all projects |
| 37 | +- `pnpm test` - Run tests using Vitest |
| 38 | +- `pnpm test:workflow` - Run workflow-specific tests |
| 39 | +- `pnpm lint` - Run ESLint across all TypeScript files with auto-fix |
| 40 | +- `pnpm format-code` - Format code using Prettier |
| 41 | + |
| 42 | +### Project-Specific Commands |
| 43 | +**Main App (projects/app/)**: |
| 44 | +- `cd projects/app && pnpm dev` - Start NextJS dev server |
| 45 | +- `cd projects/app && pnpm build` - Build NextJS app |
| 46 | +- `cd projects/app && pnpm start` - Start production server |
| 47 | + |
| 48 | +**Sandbox (projects/sandbox/)**: |
| 49 | +- `cd projects/sandbox && pnpm dev` - Start NestJS dev server with watch mode |
| 50 | +- `cd projects/sandbox && pnpm build` - Build NestJS app |
| 51 | +- `cd projects/sandbox && pnpm test` - Run Jest tests |
| 52 | + |
| 53 | +**MCP Server (projects/mcp_server/)**: |
| 54 | +- `cd projects/mcp_server && bun dev` - Start with Bun in watch mode |
| 55 | +- `cd projects/mcp_server && bun build` - Build MCP server |
| 56 | +- `cd projects/mcp_server && bun start` - Start MCP server |
| 57 | + |
| 58 | +### Utility Commands |
| 59 | +- `pnpm create:i18n` - Generate i18n translation files |
| 60 | +- `pnpm api:gen` - Generate OpenAPI documentation |
| 61 | +- `pnpm initIcon` - Initialize icon assets |
| 62 | +- `pnpm gen:theme-typings` - Generate Chakra UI theme typings |
| 63 | + |
| 64 | +## Testing |
| 65 | + |
| 66 | +The project uses Vitest for testing with coverage reporting. Key test commands: |
| 67 | +- `pnpm test` - Run all tests |
| 68 | +- `pnpm test:workflow` - Run workflow tests specifically |
| 69 | +- Test files are located in `test/` directory and `projects/app/test/` |
| 70 | +- Coverage reports are generated in `coverage/` directory |
| 71 | + |
| 72 | +## Code Organization Patterns |
| 73 | + |
| 74 | +### Monorepo Structure |
| 75 | +- Shared code lives in `packages/` and is imported using workspace references |
| 76 | +- Each project in `projects/` is a standalone application |
| 77 | +- Use `@fastgpt/global`, `@fastgpt/service`, `@fastgpt/web` imports for shared packages |
| 78 | + |
| 79 | +### API Structure |
| 80 | +- NextJS API routes in `projects/app/src/pages/api/` |
| 81 | +- Core business logic in `packages/service/core/` |
| 82 | +- Database schemas in `packages/service/` with MongoDB/Mongoose |
| 83 | + |
| 84 | +### Frontend Architecture |
| 85 | +- React components in `projects/app/src/components/` and `packages/web/components/` |
| 86 | +- Chakra UI for styling with custom theme in `packages/web/styles/theme.ts` |
| 87 | +- i18n support with files in `packages/web/i18n/` |
| 88 | +- State management using React Context and Zustand |
| 89 | + |
| 90 | +### Workflow System |
| 91 | +- Visual workflow editor using ReactFlow |
| 92 | +- Workflow engine in `packages/service/core/workflow/` |
| 93 | +- Node definitions in `packages/global/core/workflow/template/` |
| 94 | +- Dispatch system for executing workflow nodes |
| 95 | + |
| 96 | +## Development Notes |
| 97 | + |
| 98 | +- **Package Manager**: Uses pnpm with workspace configuration |
| 99 | +- **Node Version**: Requires Node.js >=18.16.0, pnpm >=9.0.0 |
| 100 | +- **Database**: Supports MongoDB, PostgreSQL with pgvector, or Milvus for vector storage |
| 101 | +- **AI Integration**: Supports multiple AI providers through unified interface |
| 102 | +- **Internationalization**: Full i18n support for Chinese, English, and Japanese |
| 103 | + |
| 104 | +## Key File Patterns |
| 105 | + |
| 106 | +- `.ts` and `.tsx` files use TypeScript throughout |
| 107 | +- Database schemas use Mongoose with TypeScript |
| 108 | +- API routes follow NextJS conventions |
| 109 | +- Component files use React functional components with hooks |
| 110 | +- Shared types defined in `packages/global/` with `.d.ts` files |
| 111 | + |
| 112 | +## Environment Configuration |
| 113 | + |
| 114 | +- Configuration files in `projects/app/data/config.json` |
| 115 | +- Environment-specific configs supported |
| 116 | +- Model configurations in `packages/service/core/ai/config/` |
0 commit comments