84 lines
4.1 KiB
Markdown
84 lines
4.1 KiB
Markdown
# 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
|