Added readme

Author: D-K-P

product-image-generator/README.md

@@ -1,231 +1,103 @@
-# AI Product Image Generator
+# Product Image Generator using Trigger.dev and Replicate
 
-Transform product photos into professional marketing materials using AI-powered image generation.
+AI-powered product image generator that transforms basic product photos into professional marketing shots using Replicate's image generation models and Trigger.dev for task orchestration.
 
-Upload a product image and automatically generate three marketing variations: isolated table shots, lifestyle scenes, and hero presentations. Built with Next.js, Trigger.dev, and OpenAI's DALL-E 3.
-Upload a product image and automatically generate three marketing variations: isolated table shots, lifestyle scenes, and hero presentations. Built with Next.js, Trigger.dev, and the AI SDK (Replicate Flux for image generation, OpenAI for analysis).
+## Tech stack
 
-## Features
+- [**Next.js**](https://nextjs.org/) – frontend React framework
+- [**Replicate**](https://replicate.com/docs) – AI image generation
+- [**Trigger.dev**](https://trigger.dev/docs) – background task orchestration
+- [**UploadThing**](https://uploadthing.com/) – file upload handling
+- [**Cloudflare R2**](https://developers.cloudflare.com/r2/) – image storage
 
-- Real-time progress tracking with WebSocket subscriptions
-- Product-focused AI prompts that maintain identical product appearance
-- Responsive design with portrait-oriented image cards
-- Automatic upload to Cloudflare R2 with public URLs
-- Individual retry mechanisms for failed generations
-- One-click download functionality
-- Parallel processing for multiple image generations
+## Setup & Running locally
 
-## Architecture
+1. **Clone the repository**
 
-### Task Structure
+   ```bash
+   git clone <repository-url>
+   cd product-image-generator
+   ```
 
-```
-uploadImageToR2
-├── Handles user image uploads to Cloudflare R2 storage
-├── Analyzes the product with OpenAI (structured JSON)
-├── 5-step progress tracking via metadata
+2. **Install dependencies**
 
-generateAndUploadImage
-├── Generates an image using Replicate Flux (img2img)
-├── Uploads result to R2 storage
-├── 4-step progress tracking via metadata
-```
+   ```bash
+   pnpm install
+   ```
 
-### Component Architecture
+3. **Copy environment variables and configure**
 
-```
-UploadCard (aspect-[3/4])
-├── Drag & drop image upload
-├── Progress tracking via run subscription
-├── On completion, parent triggers 3 individual generations
+   ```bash
+   cp env.example .env
+   ```
 
-GeneratedCard (aspect-[3/4])
-├── Individual task progress tracking
-├── Real-time image display via subscription
-├── Download and retry functionality
+   Fill in the required variables:
 
-CustomPromptCard (aspect-[3/4])
-├── Lets user enter a freeform scene prompt
-├── Triggers a single generation reusing the product analysis
+   - `TRIGGER_SECRET_KEY` – Get from [Trigger.dev dashboard](https://trigger.dev/)
+   - `REPLICATE_API_TOKEN` – Get from [Replicate](https://replicate.com/account/api-tokens)
+   - `UPLOADTHING_TOKEN` – Get from [UploadThing](https://uploadthing.com/)
+   - `R2_ACCOUNT_ID`, `R2_BUCKET`, `R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_PUBLIC_URL` – Configure Cloudflare R2 storage
+   - `OPENAI_API_KEY` – Get from [OpenAI](https://platform.openai.com/api-keys) (optional, for future features)
 
-Main Page
-├── Grid layout: 1 upload + 3 generated cards (top) + 4 custom slots (bottom)
-├── State for run IDs/access tokens for each card
-├── Triggers generations and handles retries
-```
+4. **Add Trigger.dev project reference**
 
-## Getting Started
+   Update `trigger.config.ts` with your project ref:
 
-### Prerequisites
+   ```typescript
+   project: "your_project_ref_here";
+   ```
 
-- Node.js 18+ and pnpm
-- Trigger.dev account and project
-- OpenAI API key (for product analysis)
-- Replicate API token (for Flux image generation)
-- Cloudflare R2 bucket for image storage
+5. **Start development servers**
 
-### Environment Variables
+   ```bash
+   # Terminal 1: Start Next.js dev server
+   pnpm dev
 
-```env
-# Trigger.dev
-TRIGGER_SECRET_KEY=tr_dev_your_secret_key_here
+   # Terminal 2: Start Trigger.dev CLI
+   npx trigger.dev@latest dev
+   ```
 
-# OpenAI
-OPENAI_API_KEY=sk-your_openai_api_key_here
+## How it works
 
-# Replicate
-REPLICATE_API_TOKEN=your_replicate_api_token
+Trigger.dev orchestrates the image generation workflow through two main tasks:
 
-# Cloudflare R2 Storage
-R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
-R2_ACCESS_KEY_ID=your_r2_access_key
-R2_SECRET_ACCESS_KEY=your_r2_secret_key
-R2_BUCKET=your-bucket-name
-R2_PUBLIC_URL=https://your-public-domain.com
-```
+1. **`generateImages`** – Batch coordinator that triggers multiple individual image generations ([`app/trigger/generate-images.ts`](app/trigger/generate-images.ts))
+2. **`generateImage`** – Individual image processor that:
+   - Enhances prompts with style-specific instructions
+   - Calls Replicate's `google/nano-banana` model
+   - Creates waitpoint tokens for async webhook handling
+   - Waits for Replicate completion via webhook callbacks
+   - Uploads generated images to Cloudflare R2
+   - Returns public URLs for display
 
-### Installation
+**Process flow:**
 
-```bash
-# Install dependencies
-pnpm install
+1. User selects and uploads product image to the website
+2. Image is uploaded to UploadThing cloud storage
+3. UploadThing's `onUploadComplete` callback triggers batch generation for 3 preset styles
+4. Each style runs as separate Trigger.dev task with waitpoints for Replicate webhooks
+5. Frontend receives real-time progress updates via Trigger.dev React hooks
+6. Generated images are stored in Cloudflare R2 and displayed with download options
 
-# Start development server
-pnpm dev
+**Style presets:**
 
-# Start Trigger.dev dev server (separate terminal)
-pnpm dlx trigger.dev@latest dev
-```
+- **Clean Product Shot** – Professional white background with studio lighting
+- **Lifestyle Scene** – Person holding product with natural lighting
+- **Hero Shot** – Elegant hands presenting product with dramatic lighting
 
-### Quickstart (happy path)
+## Relevant code
 
-```bash
-cp .env.example .env # if provided, otherwise create .env with the vars above
-pnpm install
-pnpm dev &
-pnpm dlx trigger.dev@latest dev
-```
+- **Image generation tasks** – Batch processing with waitpoints for Replicate webhook callbacks ([`app/trigger/generate-images.ts`](app/trigger/generate-images.ts))
+- **Upload handler** – UploadThing integration that triggers batch generation for 3 preset styles ([`app/api/uploadthing/core.ts`](app/api/uploadthing/core.ts))
+- **Real-time progress UI** – Live task updates using Trigger.dev React hooks ([`app/components/GeneratedCard.tsx`](app/components/GeneratedCard.tsx))
+- **Custom prompt interface** – User-defined style generation with custom prompts ([`app/components/CustomPromptCard.tsx`](app/components/CustomPromptCard.tsx))
+- **Main app component** – Layout and state management with professional style presets ([`app/ProductImageGenerator.tsx`](app/ProductImageGenerator.tsx))
+- **Trigger.dev configuration** – Project settings and task directories ([`trigger.config.ts`](trigger.config.ts))
 
-## Usage
+## Learn more
 
-1. Upload a product image via drag & drop or file selection
-2. The upload task runs with 5-step progress and returns a public URL + analysis
-3. The page triggers three `generateAndUploadImage` tasks (table, lifestyle, hero)
-4. Each `GeneratedCard` subscribes to its run and shows progress
-5. When a run completes, the image auto-appears, with expand/download actions
-6. You can retry any failed generation individually
-7. After the top row completes, use custom cards to generate extra scenes
-
-## Technical Implementation
-
-### AI Prompt Engineering
-
-Each generation builds an enhanced prompt from the structured product analysis. It enforces:
-
-- Product consistency: EXACT same product as the reference (brand, model, colors, text)
-- Preservation: shape/proportions/materials/logos must be unchanged
-- Variation: only background, lighting, and camera angle may change
-
-### Progress Tracking Implementation
-
-- Upload Task: 5 steps (prepare → process → upload → analyze → complete)
-- Generation Task: 4 steps (prepare → prompt → generate → upload/complete)
-- Real-time updates via `useRealtimeRun()` or `runs.subscribeToRun()` using public access tokens
-
-### Image Processing
-
-- Size: Defaults to 1024x1024 (configurable)
-- Display: `object-cover` in generated cards
-- Storage: Cloudflare R2 with automatic public URL generation
-
-## Project Structure
-
-```
-src/
-├── trigger/
-│   ├── image-upload.ts              # Upload to R2 + structured product analysis (OpenAI)
-│   └── generate-image-and-upload.ts # Flux generation (Replicate) + R2 upload
-├── app/
-│   ├── actions.ts                   # Server actions: trigger tasks + public tokens
-│   ├── components/
-│   │   ├── UploadCard.tsx           # Upload with realtime progress
-│   │   ├── GeneratedCard.tsx        # Generated image display + progress
-│   │   └── CustomPromptCard.tsx     # Freeform prompt generation (post-upload)
-│   └── page.tsx                     # Main application interface
-└── trigger.config.ts                # Trigger.dev configuration
-```
-
-## Task Flow Details
-
-### Upload Flow
-
-1. `UploadCard` calls `uploadImageToR2Action` (server action)
-2. Server action triggers `uploadImageToR2` task and creates a public token
-3. Client subscribes to the run using the token; task uploads to R2
-4. Task performs structured product analysis (OpenAI GPT-4o)
-5. On completion, the page receives `publicUrl` and `productAnalysis`
-
-### Generation Flow
-
-1. The page calls `generateSingleImageAction` three times (table/lifestyle/hero)
-2. Each task builds an enhanced prompt from `productAnalysis`
-3. Flux (Replicate) generates an img2img output referencing the base image URL
-4. The task uploads the result to R2 and sets `metadata.result.publicUrl`
-5. `GeneratedCard` subscribes and renders the image on completion
-
-### Error Handling
-
-- Individual task failures don't affect other generations
-- Retry triggers only that specific style
-- Errors are surfaced via run metadata and UI messages
-
-## Customization
-
-### Adding Generation Styles
-
-Add a new style key in `generate-image-and-upload.ts` inside `stylePrompts` and wire a corresponding button/card in `app/page.tsx`.
-
-### Modifying Image Dimensions
-
-Pass a different `size` when triggering `generateAndUploadImage` via the server action (e.g., `"1792x1024"` or `"1024x1792"`).
-
-### Custom Progress Messages
-
-Update `metadata.set("progress", ...)` in the respective task to change UX copy.
-
-## Deployment
-
-### Production Deployment
-
-```bash
-# Deploy tasks to Trigger.dev
-pnpm dlx trigger.dev@latest deploy
-
-# Deploy frontend (e.g., Vercel)
-vercel deploy
-```
-
-### Environment Configuration
-
-- Add all environment variables to deployment platform
-- Configure R2 bucket CORS for production domain
-- Update `R2_PUBLIC_URL` for production storage access
-- Ensure OpenAI API key has sufficient credits and rate limits
-
-## Development Notes
-
-### Key Implementation Details
-
-- Uses public access tokens to enable client-side run subscriptions
-- `aspect-[3/4]` Tailwind class for portrait card layout
-- Metadata carries progress + final result for robust UI updates
-
-### Performance Considerations
-
-- Parallel task execution for multiple image generations
-- Cloud storage with aggressive cache headers for assets
-- Consider API quotas for Replicate/OpenAI
-
-## License
-
-MIT License - see LICENSE file for details.
+- [**Trigger.dev waitpoints**](https://trigger.dev/docs/wait-for-token) – pause tasks for async webhook callbacks
+- [**Trigger.dev React hooks**](https://trigger.dev/docs/frontend/react-hooks) – real-time task updates and frontend integration
+- [**Trigger.dev batch operations**](https://trigger.dev/docs/tasks/batch-trigger) – parallel task execution patterns
+- [**Replicate API**](https://replicate.com/docs/get-started/nextjs) – AI model integration and webhook handling
+- [**UploadThing**](https://docs.uploadthing.com/) – file upload handling and server callbacks

product-image-generator/trigger.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from "@trigger.dev/sdk";
 
 export default defineConfig({
-  project: "proj_xjminyoyogxbrfipkrkt",
+  project: "your_project_ref_here",
   runtime: "node",
   logLevel: "log",
   // The max compute seconds a task is allowed to run. If the task run exceeds this duration, it will be stopped.