managarten/apps/picture/docs/BATCH_GENERATION_PLAN.md

🚀 Batch Generation Implementation Plan

📋 Übersicht

Implementierung eines Batch Generation Systems, das es Nutzern ermöglicht, mehrere Bilder gleichzeitig mit verschiedenen Prompts oder Variationen zu generieren.

---

🎯 Ziele & Requirements

Funktionale Anforderungen

• Batch-Größe: 2-10 Bilder pro Batch
• Parallel Processing: Bis zu 3 gleichzeitige Generierungen
• Queue Management: FIFO-Queue für wartende Generierungen
• Progress Tracking: Echtzeit-Status für jede Generierung
• Batch Actions: Alle speichern, alle löschen, alle taggen
• Fehlerbehandlung: Einzelne Fehler stoppen nicht den ganzen Batch

Nicht-Funktionale Anforderungen

• Performance: Max. 100ms UI Response Time
• Skalierbarkeit: Support für 100+ User gleichzeitig
• UX: Intuitive, nicht-blockierende UI
• Reliability: Automatic Retry bei Timeouts

---

🏗️ Architektur

1. Datenbank-Schema (Supabase)

-- Neue Tabelle: batch_generations
CREATE TABLE batch_generations (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  name TEXT,
  total_count INTEGER NOT NULL,
  completed_count INTEGER DEFAULT 0,
  failed_count INTEGER DEFAULT 0,
  status TEXT CHECK (status IN ('pending', 'processing', 'completed', 'partial', 'failed')),
  created_at TIMESTAMPTZ DEFAULT NOW(),
  completed_at TIMESTAMPTZ,

  -- Shared settings for the batch
  model_id TEXT,
  model_version TEXT,
  width INTEGER,
  height INTEGER,
  steps INTEGER,
  guidance_scale FLOAT,

  CONSTRAINT valid_counts CHECK (
    completed_count >= 0 AND
    failed_count >= 0 AND
    completed_count + failed_count <= total_count
  )
);

-- Erweiterte image_generations Tabelle
ALTER TABLE image_generations ADD COLUMN batch_id UUID REFERENCES batch_generations(id) ON DELETE SET NULL;
ALTER TABLE image_generations ADD COLUMN batch_index INTEGER;
ALTER TABLE image_generations ADD COLUMN retry_count INTEGER DEFAULT 0;
ALTER TABLE image_generations ADD COLUMN priority INTEGER DEFAULT 0;

-- Index für Performance
CREATE INDEX idx_batch_generations_user_status ON batch_generations(user_id, status);
CREATE INDEX idx_image_generations_batch ON image_generations(batch_id, batch_index);

-- Real-time Subscriptions View
CREATE VIEW batch_progress AS
SELECT
  bg.id,
  bg.user_id,
  bg.total_count,
  bg.completed_count,
  bg.failed_count,
  bg.status,
  COUNT(ig.id) FILTER (WHERE ig.status = 'processing') as processing_count,
  ARRAY_AGG(
    json_build_object(
      'id', ig.id,
      'index', ig.batch_index,
      'prompt', ig.prompt,
      'status', ig.status,
      'progress',
        CASE
          WHEN ig.status = 'completed' THEN 100
          WHEN ig.status = 'processing' THEN 50
          WHEN ig.status = 'failed' THEN -1
          ELSE 0
        END
    ) ORDER BY ig.batch_index
  ) as items
FROM batch_generations bg
LEFT JOIN image_generations ig ON ig.batch_id = bg.id
GROUP BY bg.id;

2. Backend Architecture

Edge Function: batch-generate-images

// Neue Edge Function für Batch Processing
interface BatchRequest {
	prompts: Array<{
		text: string;
		negative_prompt?: string;
		seed?: number;
	}>;
	shared_settings: {
		model_id: string;
		model_version: string;
		width: number;
		height: number;
		steps: number;
		guidance_scale: number;
	};
	batch_name?: string;
}

// Workflow:
// 1. Validate batch size (max 10)
// 2. Create batch_generation record
// 3. Create image_generation records for each prompt
// 4. Queue generations with priority
// 5. Return batch_id for tracking

Queue Worker System

// Background worker (kann als Cron Job oder separate Edge Function laufen)
interface QueueWorker {
	// Polls für neue Jobs alle 5 Sekunden
	pollInterval: 5000;

	// Max parallel Generierungen pro User
	maxParallelPerUser: 3;

	// Global max parallel
	maxParallelGlobal: 20;

	// Retry Logic
	maxRetries: 3;
	retryDelay: [5000, 10000, 30000]; // Exponential backoff
}

3. Frontend Architecture

Neue Komponenten

// components/batch/BatchGenerationModal.tsx
interface BatchGenerationModalProps {
	isOpen: boolean;
	onClose: () => void;
	onSubmit: (batch: BatchRequest) => void;
}

// components/batch/BatchPromptInput.tsx
interface BatchPromptInputProps {
	prompts: PromptItem[];
	onChange: (prompts: PromptItem[]) => void;
	maxPrompts: number;
}

// components/batch/BatchProgressTracker.tsx
interface BatchProgressTrackerProps {
	batchId: string;
	onComplete?: () => void;
	onItemClick?: (itemId: string) => void;
}

// components/batch/BatchResultsGrid.tsx
interface BatchResultsGridProps {
	batchId: string;
	results: BatchResult[];
	onSaveAll: () => void;
	onDeleteAll: () => void;
}

Neuer Store: batchStore.ts

interface BatchStore {
	// State
	activeBatches: Map<string, BatchGeneration>;
	currentBatch: BatchGeneration | null;

	// Actions
	createBatch: (request: BatchRequest) => Promise<string>;
	subscribeToBatch: (batchId: string) => void;
	unsubscribeFromBatch: (batchId: string) => void;

	// Batch Actions
	saveAllImages: (batchId: string) => Promise<void>;
	deleteAllImages: (batchId: string) => Promise<void>;
	retryFailed: (batchId: string) => Promise<void>;

	// UI State
	isBatchModalOpen: boolean;
	openBatchModal: () => void;
	closeBatchModal: () => void;
}

---

🎨 UI/UX Design

User Flow

1. Initiierung

   • Button "Batch Generation" in Generate Screen
   • Öffnet Modal/Neue Seite

2. Prompt-Eingabe

   ┌─────────────────────────────────────┐
   │ Batch Generation (3/10)             │
   │                                     │
   │ Shared Settings:                   │
   │ Model: [Flux Schnell ▼]           │
   │ Size: [1:1 ▼]                     │
   │                                     │
   │ Prompts:                           │
   │ 1. [A cyberpunk city at night    ] │
   │ 2. [Abstract colorful painting   ] │
   │ 3. [Portrait of a robot         ] │
   │ + Add Prompt                       │
   │                                     │
   │ □ Variations Mode (same prompt)    │
   │   Seeds: [Random] [+Add Seed]      │
   │                                     │
   │ [Cancel]        [Generate Batch]   │
   └─────────────────────────────────────┘
   

3. Progress Tracking

   ┌─────────────────────────────────────┐
   │ Generating Batch "My Batch"         │
   │                                     │
   │ Overall: ████░░░░░░ 40% (2/5)      │
   │                                     │
   │ 1. ✅ Cyberpunk city               │
   │ 2. ✅ Abstract painting            │
   │ 3. ⚡ Robot portrait (50%)         │
   │ 4. ⏳ Waiting...                   │
   │ 5. ⏳ Waiting...                   │
   │                                     │
   │ [Run in Background] [View Results] │
   └─────────────────────────────────────┘
   

4. Results View

   ┌─────────────────────────────────────┐
   │ Batch Results (5/5 completed)       │
   │                                     │
   │ [Grid of generated images]         │
   │                                     │
   │ Actions:                           │
   │ [Save All] [Tag All] [Delete All]  │
   │ [Generate Similar] [Export Batch]  │
   └─────────────────────────────────────┘
   

Mobile Responsiveness

• Swipeable prompt cards auf Mobile
• Bottom Sheet für Batch Modal
• Compact Progress View als Notification Bar

---

📝 Implementierungsschritte

Phase 1: Backend Foundation (3 Tage)

• Datenbank-Schema erstellen und migrieren
• Batch Edge Function implementieren
• Queue Worker Logik entwickeln
• Error Handling & Retry Logic

Phase 2: Core Frontend (3 Tage)

• BatchStore mit Zustand implementieren
• Batch Generation Modal UI
• Prompt Input Komponenten
• Real-time Subscriptions Setup

Phase 3: Progress & Results (2 Tage)

• Progress Tracker Komponente
• Real-time Updates via Supabase
• Results Grid mit Actions
• Batch Management (Save/Delete All)

Phase 4: Polish & Edge Cases (2 Tage)

• Error States & Recovery
• Loading States & Skeletons
• Mobile Optimierung
• Performance Testing
• Documentation

---

🔧 Technische Details

Parallel Processing Logic

// Pseudo-Code für Queue Worker
async function processQueue() {
	// Get active generations per user
	const activeByUser = await getActiveGenerationsGroupedByUser();

	// Find users with capacity
	const usersWithCapacity = activeByUser.filter((u) => u.activeCount < MAX_PARALLEL_PER_USER);

	// Get next pending generations
	const pending = await getNextPendingGenerations({
		limit: MAX_PARALLEL_GLOBAL - currentActiveTotal,
		excludeUsers: usersAtCapacity,
	});

	// Start generations
	for (const gen of pending) {
		startGeneration(gen);
	}
}

Real-time Updates

// Frontend Subscription
useEffect(() => {
	const subscription = supabase
		.channel(`batch_${batchId}`)
		.on(
			'postgres_changes',
			{
				event: 'UPDATE',
				schema: 'public',
				table: 'image_generations',
				filter: `batch_id=eq.${batchId}`,
			},
			(payload) => {
				updateBatchProgress(payload.new);
			}
		)
		.subscribe();

	return () => subscription.unsubscribe();
}, [batchId]);

Error Recovery

// Automatic Retry mit Exponential Backoff
async function retryGeneration(genId: string, attempt: number) {
	const delays = [5000, 15000, 30000];
	const delay = delays[Math.min(attempt, delays.length - 1)];

	await wait(delay);

	try {
		await generateImage(genId);
	} catch (error) {
		if (attempt < MAX_RETRIES - 1) {
			await retryGeneration(genId, attempt + 1);
		} else {
			await markAsFailed(genId, error);
		}
	}
}

---

📊 Success Metrics

Performance KPIs

• Queue Processing Time: < 10s für Start der ersten Generierung
• Parallel Efficiency: 80%+ GPU Utilization
• Error Rate: < 5% Failed Generations
• User Wait Time: < 2min für 5-Bilder Batch

User Experience KPIs

• Adoption Rate: 30% der aktiven User nutzen Batch
• Completion Rate: 90% der gestarteten Batches werden komplett
• Satisfaction: 4.5+ Stars für Feature

---

🚨 Risiken & Mitigationen

Risiko 1: API Rate Limits

Mitigation:

• Intelligentes Queue Management
• User-basierte Rate Limits
• Fallback auf sequentielle Verarbeitung

Risiko 2: Kosten-Explosion

Mitigation:

• Credits-System parallel implementieren
• Batch-Limits pro User/Tag
• Cost Alerts & Monitoring

Risiko 3: UI Complexity

Mitigation:

• Progressive Disclosure (Simple/Advanced Mode)
• Gute Defaults
• In-App Tutorial

---

🎯 MVP Scope (für erste Version)

Included ✅

• Basis Batch Generation (bis 5 Bilder)
• Einfache Progress Anzeige
• Save All / Delete All Actions
• Desktop & Mobile UI

Excluded ❌ (für später)

• Variations Mode
• Custom Seeds pro Prompt
• Batch Templates
• Export als ZIP
• Batch Scheduling

---

📅 Timeline

Woche 1:

• Mo-Mi: Backend Implementation
• Do-Fr: Core Frontend

Woche 2:

• Mo-Di: Progress & Results UI
• Mi-Do: Testing & Bug Fixes
• Fr: Documentation & Release

Total: 10 Arbeitstage

---

Erstellt: Januar 2025