mini-game-ai/CODEBUDDY.md

CODEBUDDY.md This file provides guidance to CodeBuddy when working with code in this repository.

Commands

Command	Description
npm run dev	Start dev server with Turbopack (fast refresh)
npm run build	Production build
npm run start	Run production server
npm run lint	ESLint check
npm run type-check	TypeScript type checking without emit
npm run format	Format code with Prettier

Architecture

Tech Stack

• Framework: Next.js 15 with App Router, React 19
• State: Zustand for client state
• Styling: Tailwind CSS with HSL CSS variables (dark mode by default)
• UI Components: Custom components built on Radix UI primitives + class-variance-authority
• Animations: Framer Motion
• Form Validation: Zod
• Media Processing: Sharp (images), FFmpeg (video/audio)
• Internationalization: i18n store + server helpers (cookie/Accept-Language detection)

Directory Structure

src/
├── app/                      # Next.js App Router
│   ├── (auth)/               # Auth routes group
│   ├── (dashboard)/          # Dashboard routes with Sidebar layout
│   │   └── tools/            # Tool pages (image/audio/video/texture-atlas)
│   ├── api/                  # API routes
│   │   ├── upload/           # File upload endpoint
│   │   └── process/          # Processing endpoints per tool type
│   ├── globals.css           # Global styles with CSS variables
│   └── layout.tsx            # Root layout (Header + Footer + SEO)
├── components/
│   ├── layout/               # Header, Footer, Sidebar, LanguageSwitcher
│   ├── seo/                  # StructuredData
│   ├── tools/                # Tool components (FileUploader, ConfigPanel, ResultPreview...)
│   │   └── atlas/            # Texture-atlas specific panels
│   └── ui/                   # Base UI primitives (button, card, dialog, etc.)
├── hooks/                    # Custom hooks (e.g., atlas worker bridge)
├── lib/                      # API clients, i18n, atlas algorithms, image processing
├── locales/                  # i18n resources
├── store/                    # Zustand stores (upload/atlas/auth)
└── types/                    # Shared TypeScript types

Key Patterns

Route Groups: Uses (auth) and (dashboard) route groups. Dashboard routes share a layout with Sidebar.

Tool Pages Pattern: Tools (audio-compress, image-compress, video-frames) share a common UI flow:

1. FileUploader for drag-drop input
2. ConfigPanel for tool-specific settings
3. ProgressBar for processing status
4. ResultPreview for outputs
5. State managed via useUploadStore

Texture Atlas Tool: /tools/texture-atlas uses a three-panel layout (file list, canvas preview, config panel) with Web Worker processing for packing and preview.

API Routes: app/api/ routes run on Node.js. Upload and processing endpoints validate input and return JSON. Production processing is intended to use Sharp/FFmpeg.

State Management: Zustand stores in store/ directory.

• uploadStore: file queue and processing progress
• atlasStore: texture-atlas state (sprites, configs, results, preview)
• authStore: user state placeholder

Internationalization: useI18nStore + useSafeTranslation to avoid SSR/CSR hydration mismatch; server uses cookie/Accept-Language to set locale.

Styling: Uses cn() from lib/utils.ts for Tailwind class merging. Theme colors are CSS variables in globals.css.

Type Definitions: Shared types live in types/index.ts (uploads, processing configs, atlas models, API responses).

Service & Processing Logic

• lib/api.ts: API client wrappers (upload/process/download/quota)
• lib/atlas-packer.ts + lib/atlas-worker.ts: browser-side packing algorithms
• hooks/useAtlasWorker.ts: Web Worker bridge for atlas packing
• lib/image-processor.ts: Sharp-based image compression pipeline
• lib/file-storage.ts: temp storage, validation, cleanup, downloads