file-starter/CLAUDE.md

CLAUDE.md

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

Development Commands

Build and Run:

• pnpm run dev - Start development server on port 8080
• pnpm run build - Build both client and server
• pnpm run build:client - Build client only
• pnpm run build:server - Build server only
• pnpm start - Start production server

Database:

• MySQL database runs on localhost:3306 (default credentials: root/empty)
• Redis runs on localhost:6379
• MinIO runs on localhost:9000/9001 (credentials: minioadmin/minioadmin)
• Use docker-compose up to start all services

Architecture Overview

Frontend (src/client/):

• React 19 + TypeScript + Vite
• Two main sections: admin/ and home/
• Uses Radix UI components and Tailwind CSS
• React Router for navigation
• React Hook Form for forms
• TanStack Query for API calls

Backend (src/server/):

• Hono.js framework with OpenAPI support
• TypeORM with MySQL database
• Modular structure under src/server/modules/
• JWT authentication
• File storage with MinIO integration

Key Modules:

• users/ - User management and authentication
• files/ - File upload/download functionality
• payments/ - Payment processing
• membership/ - Membership plans
• templates/ - Document templates
• documents/ - Document processing (Word merge feature)

API Structure:

• OpenAPI documentation available at /doc
• API routes defined in src/server/api/
• Client API calls in src/client/api.ts

Development Patterns

Form Validation:

• Frontend uses React Hook Form with Zod validation
• Backend uses Zod with z.coerce for type conversion
• Always use dayjs objects instead of native Date objects

Database:

• TypeORM entities with decorators
• Migrations in src/server/migrations/
• Environment variables for database configuration

File Handling:

• MinIO integration for file storage
• File upload/download utilities
• Document processing with docxtemplater and mammoth

Common Issues & Solutions

1. Date validation errors: Use dayjs() instead of new Date()
2. OpenAPI path parameters: Use {id} format instead of :id
3. Type coercion: Use z.coerce.number() and z.coerce.boolean() for URL params
4. Form validation mismatches: Ensure frontend and backend validation rules match

Environment Setup

Required environment variables:

• DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_DATABASE
• Database defaults to localhost:3306 with root/empty credentials
• MinIO defaults to localhost:9000 with minioadmin/minioadmin

Roo Framework

The project uses Roo framework for code generation and validation:

• Commands in .roo/commands/
• API-client validation rules
• Entity-field mapping checks

Claude Code

• Always response in Chinese