popiart-node-canvas/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Development Commands

npm run dev      # Start Next.js dev server at http://localhost:3000
npm run build    # Build for production
npm run start    # Start production server
npm run lint     # Run Next.js linting
npm run test     # Run all tests with Vitest (watch mode)
npm run test:run # Run all tests once (CI mode)

Environment Setup

Create .env.local in the root directory:

GEMINI_API_KEY=your_gemini_api_key
OPENAI_API_KEY=your_openai_api_key  # Optional, for OpenAI LLM provider
KIE_API_KEY=your_kie_api_key        # Optional, for Kie.ai models (Sora, Veo, Kling, etc.)

Architecture Overview

Node Banana is a node-based visual workflow editor for AI image generation. Users drag nodes onto a React Flow canvas, connect them via typed handles, and execute pipelines that call AI APIs.

Core Stack

• Next.js 16 (App Router) with TypeScript
• @xyflow/react (React Flow) for the node editor canvas
• Konva.js / react-konva for canvas annotation drawing
• Zustand for state management (single store pattern)

Key Files

Purpose	Location
Central workflow state & execution logic	src/store/workflowStore.ts
All TypeScript type definitions	src/types/index.ts
Main canvas component & connection validation	src/components/WorkflowCanvas.tsx
Base node component (shared by all nodes)	src/components/nodes/BaseNode.tsx
Image generation API route	src/app/api/generate/route.ts
LLM text generation API route	src/app/api/llm/route.ts
Cost calculations	src/utils/costCalculator.ts
Grid splitting utility	src/utils/gridSplitter.ts

State Management

All application state lives in workflowStore.ts using Zustand. Key patterns:

• useWorkflowStore() hook provides access to nodes, edges, and all actions
• executeWorkflow(startFromNodeId?) runs the pipeline via topological sort
• getConnectedInputs(nodeId) retrieves upstream data for a node
• updateNodeData(nodeId, partialData) updates node state
• Auto-save runs every 90 seconds when enabled

Execution Flow

1. User clicks Run or presses Cmd/Ctrl+Enter
2. executeWorkflow() performs topological sort on node graph
3. Nodes execute in dependency order, calling APIs as needed
4. getConnectedInputs() provides upstream images/text to each node
5. Locked groups are skipped; pause edges halt execution

AI Models

Image generation models (these exist and are recently released):

• gemini-2.5-flash-preview-image-generation → internal name: nano-banana
• gemini-3-pro-image-preview → internal name: nano-banana-pro

LLM models:

• Google: gemini-2.5-flash, gemini-3-flash-preview, gemini-3-pro-preview
• OpenAI: gpt-4.1-mini, gpt-4.1-nano

Node Types

Type	Purpose	Inputs	Outputs
imageInput	Load/upload images	reference	image
annotation	Draw on images (Konva)	image	image
prompt	Text prompt input	none	text
nanoBanana	AI image generation	image, text	image
llmGenerate	AI text generation	text, image	text
splitGrid	Split image into grid cells	image	reference
output	Display final result	image	none

Node Connection System

Handle Types

Handle Type	Data Format	Description
image	Base64 data URL	Visual content
text	String	Text content

Connection Rules

1. Type Matching: Handles only connect to matching types (image→image, text→text)
2. Direction: Connections flow from source (output) to target (input)
3. Multiplicity: Image inputs accept multiple connections; text inputs accept one

Data Flow in getConnectedInputs

Returns { images: string[], text: string | null }.

Image data extracted from:

• imageInput → data.image
• annotation → data.outputImage
• nanoBanana → data.outputImage

Text data extracted from:

• prompt → data.prompt
• llmGenerate → data.outputText

Keyboard Shortcuts

• Cmd/Ctrl + Enter - Run workflow
• Cmd/Ctrl + C/V - Copy/paste nodes
• Shift + P - Add prompt node at center
• Shift + I - Add image input node
• Shift + G - Add generate (nanoBanana) node
• Shift + V - Add video (generateVideo) node
• Shift + L - Add LLM node
• Shift + A - Add annotation node
• H - Stack selected nodes horizontally
• V - Stack selected nodes vertically
• G - Arrange selected nodes in grid

Adding New Node Types

1. Define the data interface in src/types/index.ts
2. Add to NodeType union in src/types/index.ts
3. Create default data in createDefaultNodeData() in workflowStore.ts
4. Add dimensions to defaultDimensions in workflowStore.ts
5. Create the component in src/components/nodes/
6. Export from src/components/nodes/index.ts
7. Register in nodeTypes in WorkflowCanvas.tsx
8. Add minimap color in WorkflowCanvas.tsx
9. Update getConnectedInputs() if the node produces consumable output
10. Add execution logic in executeWorkflow() if the node requires processing
11. Update ConnectionDropMenu.tsx to include the node in source/target lists

Handle Naming Convention

Use descriptive handle IDs matching the data type:

• id="image" for image data
• id="text" for text data

Validation

• Connection validation: isValidConnection() in WorkflowCanvas.tsx
• Workflow validation: validateWorkflow() in workflowStore.ts

API Routes

All routes in src/app/api/:

Route	Timeout	Purpose
/api/generate	5 min	Image generation via Gemini
/api/llm	1 min	Text generation (Google/OpenAI)
/api/workflow	default	Save/load workflow files
/api/save-generation	default	Auto-save generated images
/api/logs	default	Session logging

localStorage Keys

• node-banana-workflow-configs - Project metadata (paths)
• node-banana-workflow-costs - Cost tracking per workflow
• node-banana-nanoBanana-defaults - Sticky generation settings

Commits

• The .planning directory is untracked, do not attempt to commit any changes to the files in this directory.

Deployment & Git Workflow

Vercel Deployment

Production URL: https://node-banana-nilas-projects-2f16eb79.vercel.app

The app is deployed on Vercel from the etailup/node-banana fork. Pushes to master trigger automatic deployments.

Environment variables required in Vercel dashboard:

• GEMINI_API_KEY
• OPENAI_API_KEY (optional)
• KIE_API_KEY (optional, for Kie.ai models)

Fork + Upstream Sync

This repo is a fork that tracks the original upstream:

Remote	Repository	Purpose
origin	etailup/node-banana	Your fork (push here, deploys to Vercel)
upstream	shrimbly/node-banana	Original source (pull updates from here)

Pull updates from original while keeping your modifications:

git fetch upstream
git merge upstream/master
# Resolve conflicts if any
git push origin master

Check remotes:

git remote -v