# VibeGallery - Requirements Document

## Overview
A website where users share AI-generated content. Built with Headless WordPress (WPGraphQL) + SvelteKit.

---

## Tech Stack

| Layer | Technology |
|-------|-----------|
| CMS / Backend | WordPress 6.x (Headless) |
| API | WPGraphQL |
| Frontend | SvelteKit + Tailwind CSS |
| Authentication | Google OAuth only |
| Translation | Polylang + LiteLLM |
| Design | Dark theme, Cyberpunk style |
| UI Language | English |
| Deployment | AWS EC2 |

---

## Content Types

5 content types: **App**, **Web**, **Image**, **Audio**, **Video**

- All content is stored as a single CPT `vg_content`
- Content type distinction is managed via `vg_content_type` taxonomy (category-like)
- Taxonomy terms: app, web, image, audio, video

### Common Fields (all types)

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| Title | Text | Yes | |
| Featured Image | Image | Yes | Thumbnail / representative image |
| URL | URL | No | Link to the content |
| Description | Textarea | Yes | |
| Prompt | Textarea | No | AI prompt used to create the content |
| Tags | Multi-select | Auto | Auto-extracted from title, description, and prompt via LLM after English translation (max 10) |
| AI Tool | Select | Yes | Tool used to create the content |

### Type-Specific Fields

| Type | Additional Fields |
|------|------------------|
| **App** | Google Play Store URL, iOS App Store URL |
| **Web** | (common fields only) |
| **Image** | (common fields only) |
| **Audio** | (common fields only) |
| **Video** | Video URL (YouTube or Vimeo), File attachment (video file) |

### Image Upload
- Featured Image is the only image upload for all content types
- Featured Image is still required separately for all content types, including Image, Audio, and Video
- Upload destination: WordPress Media Library

### Video
- Video URL (YouTube or Vimeo) **or** Video file attachment — at least one required
- On detail page, video player replaces featured image position
  - YouTube/Vimeo URLs: embedded player (iframe)
  - Uploaded video files: native `<video>` player

### File Upload
- Maximum file size: **1GB**
- Applicable to: Video content type (file attachment)

---

## AI Tools (저작툴)

- Each content type has a set of selectable AI tools
- Admin pre-defines common tools per content type
- Users can add custom AI tools when creating content
- User-added AI tools become shared options that can be selected in future content
- Tags are not manually entered by users; they are extracted automatically (up to 10) from title, description, and prompt using an LLM after English translation
- Examples:
  - App/Web: Claude Code, OpenAI Codex, Google Gemini
  - Image: Midjourney, DALL-E, Stable Diffusion
  - Audio: Suno, Udio
  - Video: Runway, Pika

---

## User Profile

### User Fields

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| Username (Slug) | Text | Yes | Unique handle, used as `/@username` URL. Stored as WordPress `user_login`. |
| Nickname | Text | Yes | Display name |
| Profile Image | Image | No | |
| Description | Textarea | No | |
| Homepage URL | URL | No | |
| Twitter URL | URL | No | |
| Instagram URL | URL | No | |
| Threads URL | URL | No | |
| LinkedIn URL | URL | No | |
| Facebook URL | URL | No | |

---

## Authentication

- **Google Login only** (no email/password registration)
- First login → redirect to **Profile Setup** page (nickname required)
- Subsequent logins → redirect to Home
- Users must complete Profile Setup before they can create content, like content, or post comments

---

## Navigation

### Header Navigation
- Logo / Home link
- **App** — link to `/app` archive
- **Web** — link to `/web` archive
- **Image** — link to `/image` archive
- **Audio** — link to `/audio` archive
- **Video** — link to `/video` archive
- **VIBE** — action button (CTA) with bolt icon, opens content type selector → create form
- User avatar / Login button (right side)

---

## Pages

### 1. Home
- **No tabs** — each content type has its own section
- Sections: App, Web, Image, Audio, Video (in order)
- Each section shows latest content in a responsive grid
- Each section has a **"View More →"** link to the archive page (`/app`, `/web`, etc.)

### 2. Content Archive (`/app`, `/web`, `/image`, `/audio`, `/video`)
- Full listing of content for a specific type
- Sort options: **Latest**, **Popular** (by like count)
- Popular sort tie-breaker: newest first
- "Load More" button pagination (click to load next page)

### 3. Content Detail (`/[type]/[slug]`)
- Full content information display
- Featured image display (except video type — shows video player instead)
- Video type: embedded YouTube/Vimeo player or native `<video>` player in featured image position
- Prompt display
- AI tool badge
- Like button (logged-in users only)
- Comment section (logged-in users only)
- Auto-translated content shown based on browser language (with "Auto-translated" badge)
- **Share button**: PC — copy URL to clipboard; Mobile — `navigator.share()` API

### 4. Content Create / Edit
- Type-specific form with all applicable fields
- AI tool selector with option to add custom tool
- Featured image upload with progress bar (all types)
- Video type: Video URL input (YouTube/Vimeo) or video file upload — at least one required
- Only content author can edit
- Tags are generated automatically from the description on create/update

### 5. User Profile (`/@username`)
- User info: avatar, nickname, description
- Social links with icons
- Grid of user's published content
- URL format: `/@` (username = WordPress `user_login`)

### 6. Profile Setup (first login)
- Username (slug) input with availability check
- Username allows lowercase English letters, numbers, and hyphens only
- Username length: 4 to 30 characters
- Nickname, profile image, description
- Social links

### 7. Profile Edit
- Edit all user fields (username cannot be changed after setup)
- Update social links

### 8. Static Pages (`/privacy`, `/terms`)
- Privacy Policy and Terms of Service pages
- Content loaded from WordPress pages via WPGraphQL
- Linked from footer

---

## Social Features

### Likes
- Logged-in users only
- Toggle like/unlike
- Display like count on gallery cards and detail page
- One active like per user per content item

### Comments
- Logged-in users only
- Display comment list with user avatar and timestamp
- Post new comment
- Flat comments only (no threaded replies)

---

## Content Moderation
- **Immediate publish** — no admin approval required
- Content author can edit/delete own content

---

## Translation System

### Polylang-based Multilingual Content
- All user-submitted content is stored with Polylang `ul_UL` language (Original/undefined)
- Each translation is a separate WordPress post linked via Polylang translation groups
- Translation targets: title, description, prompt only (other fields reference original post)

### Auto Translation Flow
1. **Content creation** → saved as `ul_UL` → async non-blocking HTTP to translate to English → English post created and linked
2. **Content display** → client sends browser language → server returns translated content if available, original if not
3. **Missing translation** → return original + fire async translation from original to target language → next request returns translated
4. **Content update** → all translation posts deleted → async re-translate to English
5. **Content delete** → original + all translation posts deleted

### Language Registration
- Polylang languages: `ul_UL` (Original), `en` (English), `ko` (Korean) pre-registered
- If browser language is not registered in Polylang, auto-register it (unlimited)

### Translation API
- Internal REST endpoint: `POST /wp-json/vg/v1/translate` (non-blocking, internal-only)
- LiteLLM for translation (title, description, prompt)
- Transient lock prevents duplicate translations

### Frontend Language Detection
- Client-side: `navigator.language` → set `vg_lang` cookie
- Server reads cookie (or `Accept-Language` header fallback) → passes `lang` to GraphQL queries
- `translationStatus` field: `"original"` | `"translated"` | `"pending"`

---

## Design

### Theme
- **Dark theme** with **cyberpunk** aesthetic
- Neon color accents (cyan, magenta, purple)
- Grid pattern background
- Glow/neon shadow effects
- Display font: Space Grotesk
- Body font: Space Grotesk
- Monospace: JetBrains Mono

### Responsive
- Mobile-first responsive design
- Breakpoints: mobile, tablet, desktop

---

## Sorting &amp; Filtering

### Sorting (MVP)
- Latest (newest first)
- Popular (most likes)
- For Popular sort, ties are ordered by newest first

### Filtering (Future)
- By content type (via navigation tabs — included in MVP)
- By AI tool (future)
- Search (future)

---

## Non-Functional Requirements

| Requirement | Detail |
|-------------|--------|
| Max file upload | 1GB |
| Authentication | Google OAuth only |
| Authorization | Content CRUD: author only. Likes/Comments: logged-in users with completed profile setup |
| SEO | Server-side rendering, meta tags, Open Graph |
| Performance | Lazy-loaded translations |
| Deployment | Single AWS EC2 instance (WordPress + SvelteKit + LiteLLM) |