# CLAUDE.md

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

## Project Overview

CastAD (formerly ADo4) is an AI-powered marketing video generation platform for pension (accommodation) businesses. It uses Google Gemini for content generation/TTS and Suno AI for music creation, with Puppeteer for server-side video rendering.

## Development Commands

```bash
# Start both frontend and backend concurrently (recommended)
./start.sh

# Or run manually:
npm run dev                    # Run frontend + backend together
npm run build                  # Build frontend for production
cd server && node index.js     # Run backend only

# Install dependencies
npm install                    # Frontend dependencies
cd server && npm install       # Backend dependencies
npm run build:all             # Install all + build frontend
```

## Architecture

### Three-Layer Structure
- **Frontend**: React 19 + TypeScript + Vite (port 3000/5173)
- **Backend**: Express.js + SQLite (port 3001)
- **External APIs**: Google Gemini, Suno AI, YouTube Data API

### Key Directories
- `components/` - React UI components (InputForm, Navbar, ResultPlayer, etc.)
- `src/pages/` - Page components (GeneratorPage, Dashboard, AdminDashboard, Login/Register)
- `src/contexts/` - Global state (AuthContext for JWT auth, LanguageContext for i18n)
- `src/locales.ts` - Multi-language translations (ko, en, ja, zh, th, vi)
- `services/` - Frontend API services (geminiService, sunoService, ffmpegService, naverService)
- `server/` - Express backend
  - `index.js` - Main server with auth, rendering, and API routes
  - `db.js` - SQLite schema (users, history tables)
  - `geminiBackendService.js` - Server-side Gemini operations
  - `youtubeService.js` - YouTube upload via OAuth
  - `downloads/` - Generated video storage
  - `temp/` - Temporary rendering files

### Data Flow
1. User inputs business info/photos → GeneratorPage.tsx
2. Frontend calls Gemini API for creative content → geminiService.ts
3. Music generation via Suno proxy → sunoService.ts
4. Render request sent to backend → server/index.js
5. Puppeteer captures video, FFmpeg merges audio → final MP4 in downloads/

### Authentication
- JWT tokens stored in localStorage
- Auth middleware in server/index.js (`authenticateToken`, `requireAdmin`)
- Roles: 'user' and 'admin'
- Default admin: `admin` / `admin123`

### Environment Variables (.env in root)
```
VITE_GEMINI_API_KEY=     # Required: Google AI Studio API key
SUNO_API_KEY=            # Required: Suno AI proxy key
JWT_SECRET=              # Required: JWT signing secret
FRONTEND_URL=            # Optional: For CORS (default: http://localhost:5173)
PORT=                    # Optional: Backend port (default: 3001)
```

## Tech Notes

- Vite proxies `/api`, `/render`, `/downloads`, `/temp` to backend (port 3001)
- Path alias `@/` maps to project root
- SQLite database at `server/database.sqlite` (not tracked in git)
- Video rendering uses Puppeteer headless Chrome + FFmpeg
- Multi-language support: UI language separate from content generation language