.

.dockerignore

@@ -0,0 +1,15 @@
+.git
+**/.venv
+**/__pycache__
+**/*.pyc
+**/node_modules
+frontend/dist
+.env
+.env.*
+**/.env.local
+storage
+showcase_output
+reference_videos
+*.mp4
+*.png
+**/.DS_Store

Dockerfile

@@ -0,0 +1,25 @@
+# syntax=docker/dockerfile:1
+# Hugging Face Spaces (Docker) — FastAPI + Vite build. Listens on $PORT (default 7860).
+
+FROM node:22-bookworm-slim AS frontend-build
+WORKDIR /app/frontend
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+COPY frontend/ ./
+RUN npm run build
+
+FROM python:3.12-slim-bookworm
+RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY backend/requirements.txt /app/backend/requirements.txt
+RUN pip install --no-cache-dir -r /app/backend/requirements.txt
+COPY backend/ /app/backend/
+COPY --from=frontend-build /app/frontend/dist /app/frontend/dist
+
+ENV PYTHONPATH=/app/backend
+ENV PORT=7860
+
+WORKDIR /app/backend
+CMD ["sh", "-c", "exec uvicorn main:app --host 0.0.0.0 --port ${PORT:-7860}"]

README.md

@@ -1,10 +1,51 @@
 ---
-title: ProductShowcaseStudio
-emoji: 📉
-colorFrom: gray
+title: Product Showcase Studio
+emoji: 🎬
+colorFrom: slate
 colorTo: indigo
 sdk: docker
-pinned: false
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Product Showcase Studio
+
+Cinematic product video pipeline: **shot planning** → **KIE Veo / Seedance** → **FFmpeg merge**, with optional **GPT Image** keyframes and **product URL** import.
+
+## Deploy on Hugging Face Spaces
+
+1. **Create a Space** → **Docker** → link this repository (or push these files to a new repo under your account).
+2. **Settings → Repository secrets** (or **Variables and secrets**): add at least:
+   - **`VITE_API_BASE_URL`** — your Space’s public app URL, same as the address in the browser when the app loads, with no trailing slash (for example `https://YOUR-USERNAME-YOUR-SPACE-NAME.hf.space`). This is required so **callback URLs** and **hosted images** use the correct origin.
+   - **`KIE_API_KEY`** — if you use KIE Veo.
+   - **`OPENAI_API_KEY`** — optional, for LLM shot plans and GPT Image keyframes.
+   - **`REPLICATE_API_TOKEN`** — optional Seedance fallback when KIE is not used.
+3. Wait for the build (Node build + Python image). Open the Space URL when the build is **Running**.
+
+The container runs **uvicorn** on **`PORT`** (Spaces set this; default **7860**). **FFmpeg** is installed for the merge step.
+
+### Local Docker (optional)
+
+```bash
+docker build -t product-showcase .
+docker run --rm -p 7860:7860 \
+  -e VITE_API_BASE_URL=http://127.0.0.1:7860 \
+  -e KIE_API_KEY=... \
+  product-showcase
+```
+
+Then open `http://127.0.0.1:7860`.
+
+## Local development
+
+See [FLOW.md](FLOW.md) for architecture and env details.
+
+```bash
+# API
+cd backend && python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt && python main.py
+
+# UI (separate terminal)
+cd frontend && npm install && npm run dev
+```
+
+With a built `frontend/dist`, `python main.py` also serves the SPA from the same origin.

backend/main.py

@@ -4,10 +4,12 @@ Video pipeline aligned with python-backend (KIE Veo, image hosting, merge).
 """
 
 from contextlib import asynccontextmanager
+from pathlib import Path
 import os
 import shutil
 
 from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
 from fastapi.middleware.cors import CORSMiddleware
 
 from api.video_generation import router as video_router
@@ -78,6 +80,10 @@ app.include_router(image_router, prefix="/api")
 app.include_router(export_router, prefix="/api")
 
 
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+_FRONTEND_DIST = _REPO_ROOT / "frontend" / "dist"
+
+
 @app.get("/health")
 def health():
     return {
@@ -96,6 +102,14 @@ def health():
     }
 
 
+if _FRONTEND_DIST.is_dir():
+    app.mount(
+        "/",
+        StaticFiles(directory=str(_FRONTEND_DIST), html=True),
+        name="frontend",
+    )
+
+
 if __name__ == "__main__":
     import uvicorn
 

backend/utils/public_url.py

@@ -10,7 +10,10 @@ def get_server_port_str() -> str:
 
 
 def get_public_base_url() -> str:
-    explicit = (os.getenv("VITE_API_BASE_URL") or "").strip().rstrip("/")
+    """Public origin for callbacks and hosted URLs. Set VITE_API_BASE_URL or PUBLIC_BASE_URL on deploy (e.g. https://YOUR-SPACE.hf.space)."""
+    explicit = (
+        (os.getenv("VITE_API_BASE_URL") or os.getenv("PUBLIC_BASE_URL") or "").strip().rstrip("/")
+    )
     if explicit:
         return explicit
     return f"http://127.0.0.1:{get_server_port_str()}"