# kv-pix (V3)

A modern, full-stack AI Image Generator with **FastAPI backend** and **Next.js frontend**. 
Powered by Google ImageFX (Whisk), Grok, and Meta AI.

## 🆕 What's New in V3

- **FastAPI Backend** - Python backend with automatic Swagger documentation
- **Better Security** - Centralized CORS, Pydantic validation, structured error handling
- **API Documentation** - Interactive docs at `/api/docs` (Swagger) and `/api/redoc`
- **Improved Architecture** - Clean separation of frontend and backend

## 🚀 Quick Start

### Prerequisites
- Node.js 18+
- Python 3.11+
- Whisk/Grok/Meta Cookies (from respective services)

### Installation

```bash
# Install frontend dependencies
npm install

# Set up backend
cd backend
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

### Run Locally

**Terminal 1 - Backend:**
```bash
cd backend
source venv/bin/activate
uvicorn main:app --reload --port 8000
```

**Terminal 2 - Frontend:**
```bash
npm run dev
```

| Service | URL |
|---------|-----|
| Frontend | http://localhost:3000 |
| Backend API | http://localhost:8000 |
| Swagger UI | http://localhost:8000/docs |
| ReDoc | http://localhost:8000/redoc |

## 🐳 Docker Deployment (Synology NAS / linux/amd64)

### Using Docker Compose (Recommended)
```bash
docker-compose up -d
```

### Using Docker CLI
```bash
# Pull from registry
docker pull git.khoavo.myds.me/vndangkhoa/apix:v3

# Run
docker run -d -p 3000:3000 -p 8000:8000 --name kv-pix git.khoavo.myds.me/vndangkhoa/apix:v3
```

## 🏗️ Architecture

```
┌─────────────────┐     HTTP/REST      ┌──────────────────┐
│   Next.js UI    │ ◄───────────────► │   FastAPI Backend │
│   (Port 3000)   │                    │   (Port 8000)     │
└─────────────────┘                    └────────┬─────────┘
                                                │
                                    ┌───────────┴───────────┐
                                    │                       │
                              ┌─────▼─────┐          ┌──────▼──────┐
                              │ WhiskAPI  │          │  MetaAI API │
                              └───────────┘          └─────────────┘
```

### Tech Stack
- **Frontend**: [Next.js 15](https://nextjs.org/) (App Router) + [Tailwind CSS](https://tailwindcss.com/)
- **Backend**: [FastAPI](https://fastapi.tiangolo.com/) + [Pydantic](https://docs.pydantic.dev/)
- **State**: [Zustand](https://github.com/pmndrs/zustand)
- **Icons**: [Lucide React](https://lucide.dev/)

### Project Structure
```
├── app/            # Next.js pages and (legacy) API routes
├── backend/        # FastAPI Python backend
│   ├── main.py
│   ├── routers/    # API endpoints
│   ├── services/   # Business logic (whisk_client, meta_client)
│   └── models/     # Pydantic request/response models
├── components/     # React UI components
├── lib/            # Frontend utilities and API client
├── data/           # Prompt library JSON
└── public/         # Static assets
```

## ✨ Features

- **Multi-Provider**: Google Whisk (ImageFX), Grok (xAI), Meta AI (Imagine)
- **FastAPI Backend**: Type-safe Python API with auto-documentation
- **Prompt Library**: Curated prompts organized by categories
- **Upload History**: Reuse previously uploaded reference images
- **Reference Chips**: Drag-and-drop references for Subject/Scene/Style
- **Video Generation**: Animate images with Whisk Animate (Veo)
- **Responsive Gallery**: Masonry layout with smooth animations
- **Dark Mode**: Material 3 inspired aesthetic

## 🍪 Cookie Configuration

1. Go to the respective service:
   - Whisk: [ImageFX](https://labs.google/fx/tools/image-fx)
   - Grok: [grok.com](https://grok.com)
   - Meta: [meta.ai](https://www.meta.ai)
2. Open DevTools (F12) → Application → Cookies.
3. Copy the cookie string (or use a "Get Cookies" extension to copy as JSON).
4. Paste into the **Settings** menu in the app.

## 📝 License
MIT