CLAUDE.md

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

Project Overview

IFMahouShoujo (魔法少女生成器) is a Magical Girl Generator - an AI-powered web application that creates personalized magical girl characters. Built with Next.js 15, React 19, Bun and TypeScript, it features a mobile-friendly design with a whimsical, magical theme.

Commands

Development

bun run dev         # Start development server with Turbopack
bun run build       # Build for production
bun run start       # Start production server
bun run lint        # Run ESLint

Environment Setup

Create a .env.local file based on env.example with:

NEXT_PUBLIC_AI_API_KEY: OpenAI API key
NEXT_PUBLIC_AI_BASE_URL: API endpoint (optional, defaults to OpenAI)
NEXT_PUBLIC_AI_MODEL: AI model (optional, defaults to gpt-3.5-turbo)

Architecture

Hybrid Routing Structure

The project uses both pages/ (traditional) and app/ (App Router) directories:

Main application logic is in pages/index.tsx
App Router is partially implemented in app/ for future migration

Core Components

pages/index.tsx: Main magical girl generator interface
lib/ai.ts: AI integration using Vercel AI SDK with OpenAI
lib/config.ts: Environment configuration management
lib/utils.ts: Utility functions including deterministic level generation

AI Integration Pattern

Uses Vercel AI SDK with Zod schemas for type-safe responses:

// Schema defined with zod
const magicalGirlSchema = z.object({
  magicalName: z.string(),
  attributes: z.object({...}),
  transformationSpell: z.string()
})

// AI generation with structured output
const { object } = await generateObject({
  model: openai(config.model),
  schema: magicalGirlSchema,
  prompt: generatePrompt(name)
})

Level System

Character levels are deterministically generated based on name hash:

种芽 (Seed) - Level 1
叶 (Leaf) - Level 2
蕾 (Bud) - Level 3
花 (Flower) - Level 4
满开 (Full Bloom) - Level 5
宝石权杖 (Gem Scepter) - Level 6

Styling Approach

Tailwind CSS 4 with custom animations
shadcn/ui components (configured in components.json)
Mobile-first responsive design
Chinese language UI

Key Dependencies

AI: @ai-sdk/openai, ai, zod
UI: tailwindcss, lucide-react, class-variance-authority
Image Export: html2canvas
Framework: next, react, typescript

Development Notes

No testing framework currently configured
API keys are client-exposed (NEXTPUBLIC*)
Project is bilingual with Chinese comments and UI text
Uses Turbopack for faster development builds

CLAUDE.md 2.7 KB Permalink History Raw