Commerce Scene Studio

English | 简体中文

An integrated ecommerce scene image generation system for prompt reverse engineering, prompt optimization, single-image generation, batch generation, and generated image history management.

Overview

Commerce Scene Studio includes a Next.js frontend and a FastAPI backend. It is designed for local development and validation of ecommerce product scene image workflows. The default AI and storage providers are mocks, so the main workflow can run locally before production credentials are configured.

Stack

• Frontend: Next.js, React, Tailwind CSS, Shadcn UI-style components
• Backend: Python FastAPI
• Database: PostgreSQL with pgvector-ready prompt retrieval schema
• Cache / Queue: Redis and Celery
• File storage: local development adapter plus OSS / S3 / COS provider interface
• AI providers: prompt reverse engineering, prompt optimization, and image generation adapters
• API: REST API and webhook callback endpoint

Core Features

• Upload product images and reverse-engineer prompts
• One-click prompt optimization
• Prompt editing and version saving
• Single-product scene image generation
• Excel plus white-background image batch generation
• Async batch task submission and progress tracking
• Generated image history
• Prompt library with vector-search-ready schema
• Webhook callback endpoint

Project Structure

.
├── backend/              # FastAPI backend service
├── src/                  # Next.js frontend source
├── docker-compose.yml    # Local PostgreSQL / Redis services
├── package.json          # Frontend dependencies and scripts
└── README.md             # Main project documentation

Local Development

1. Install frontend dependencies

npm install

2. Start the frontend

npm run dev -- --hostname 127.0.0.1 --port 3000

Open:

http://127.0.0.1:3000

Optional API base URL in PowerShell:

$env:NEXT_PUBLIC_API_BASE_URL="http://127.0.0.1:8000/api/v1"

3. Start local infrastructure

docker compose up -d postgres redis

4. Start the FastAPI backend

cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Health check:

http://127.0.0.1:8000/health

5. Start the Celery worker

cd backend
.venv\Scripts\activate
celery -A app.tasks.celery_app.celery_app worker --loglevel=info --pool=solo

Main APIs

• POST /api/v1/prompts/reverse: Reverse-engineer a prompt from an uploaded image.
• POST /api/v1/prompts/optimize: Optimize a prompt.
• GET /api/v1/prompts/versions: List saved prompt versions.
• GET /api/v1/prompts/library: Search the prompt library.
• POST /api/v1/generations: Generate one scene image.
• GET /api/v1/generations/history: List generated image history.
• POST /api/v1/batches: Create an async batch job from Excel and white-background images.
• GET /api/v1/batches/{job_id}: Track batch progress.
• POST /api/v1/webhooks/callbacks: Receive webhook callbacks.

Configuration

Backend configuration is loaded from backend/.env. Copy the example file first:

cd backend
copy .env.example .env

Do not commit production API keys, database URLs, storage credentials, or other secrets. This repository ignores .env, .env.local, .env.docker, and related local configuration files.

Development Notes

• Frontend page: src/app/page.tsx
• Frontend API client: src/lib/api-client.ts
• Backend entrypoint: backend/app/main.py
• Backend router: backend/app/api/router.py
• Async tasks: backend/app/tasks/
• Database migrations: backend/migrations/