NodeWow — Two-Level LLM Scene Orchestrator

A node-based visual pipeline that uses Gemini for two-level LLM orchestration:

1. Level 1 (Orchestrator) — Analyzes a collated multi-scene prompt and decomposes it into individual scenes and frame-level image prompts.
2. Level 2 (Parallel Workers) — Generates every frame image in parallel using Gemini's image generation API (Imagen), with BullMQ + Redis for durable job queuing.

The React Flow frontend materializes the pipeline as an auto-laid-out node graph that updates in real time via SSE.

---

Prerequisites

Tool	Version
Node.js	20+
Docker (for Redis)	Any recent
Gemini API key	Get one at AI Studio

Quick Start

# 1. Start Redis
docker compose up -d
# 2. Install + start the backendcd backend
npm install
npm run dev # http://localhost:3001# 3. In a separate terminal — install + start the frontendcd frontend
npm install
npm run dev # http://localhost:3000

Open http://localhost:3000, type a multi-scene prompt, and click Generate Frames. The graph builds itself in real time.

Environment Variables

Copy .env.example to .env at the repo root and fill in GEMINI_API_KEY. Key tunables:

Variable	Default	Purpose
GEMINI_API_KEY	—	Required. Your Google AI Studio key
REDIS_URL	redis://localhost:6379	BullMQ connection
ORCHESTRATOR_MODEL	gemini-2.5-flash	Text model for scene planning
IMAGE_MODEL	imagen-4.0-generate-001	Image generation model
FRAME_QUEUE_CONCURRENCY	5	Max parallel image generation jobs
PORT	3001	Backend HTTP port

Architecture

User prompt
│
▼
POST /api/runs ──▶ BullMQ "orchestrate" queue
│
▼
Gemini text model → JSON plan (scenes + frames)
│
▼
BullMQ "generate-frame" queue (N jobs, parallel)
│ │ │
▼ ▼ ▼
Gemini image API (one call per frame)
│ │ │
▼ ▼ ▼
SSE events → React Flow graph

Image Resolution

The image generation model produces frames at its native maximum resolution (up to ~1536×2048 for 16:9). True 4K (3840×2160) depends on model capabilities — the API is configured to request the largest output the model supports. No client-side upscaling is applied.

Project Structure

backend/
src/
config.ts — env + defaults
schema.ts — Zod schemas for plan / run request
gemini.ts — Gemini text + image wrappers
queues.ts — BullMQ queue definitions
runTracker.ts — Redis-backed completion tracker
sse.ts — EventEmitter for run events
workers/
orchestrator.ts — Level 1: plan + fan-out
frameGen.ts — Level 2: image gen + disk persist
routes/
runs.ts — POST /api/runs + GET SSE stream
assets.ts — Static image serving
index.ts — Fastify entry
frontend/
src/
app/ — Next.js App Router
components/
flow/ — Custom React Flow nodes + canvas
ui/ — Button, StatusBadge
lib/
layout.ts — ELK auto-layout
utils.ts — cn() utility