# 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