Image Generation Architecture

Bike4Mind's image generation system provides a unified interface for multiple AI image providers, supporting both synchronous and asynchronous generation workflows with real-time user feedback.

System Overview

The image generation architecture follows a layered design pattern with clear separation of concerns:

graph TB
    subgraph "Frontend Layer"
        UI[User Interface]
        State[State Management]
        Commands[Command Handlers]
    end
    
    subgraph "API Layer"
        GenAPI[Generate API]
        EditAPI[Edit API]
        UrlAPI[Signed URL API]
    end
    
    subgraph "Service Layer"
        GenService[Generation Service]
        EditService[Edit Service]
        Factory[Provider Factory]
    end
    
    subgraph "Providers"
        OpenAI[OpenAI Service]
        BFL[BFL Service]
    end
    
    subgraph "Infrastructure"
        Queue[SQS Queues]
        Storage[S3 Storage]
        WebSocket[Real-time Updates]
    end

    UI --> State
    State --> Commands
    Commands --> GenAPI
    Commands --> EditAPI
    
    GenAPI --> GenService
    EditAPI --> EditService
    
    GenService --> Factory
    EditService --> Factory
    
    Factory --> OpenAI
    Factory --> BFL
    
    GenService --> Queue
    GenService --> Storage
    GenService --> WebSocket

Core Components

Frontend Layer

Advanced AI Settings (AdvancedAISettings.tsx)

Central configuration hub for image generation parameters:

• Model Selection: Toggle between text and image models
• Dynamic Controls: Show/hide parameters based on selected model
• Parameter Validation: Enforce model-specific constraints
• Real-time Updates: Immediate feedback on parameter changes

LLM Context (LLMContext.tsx)

State management for image generation settings:

interface ImageGenerationState {
  // Model selection
  model: ImageModelName;
  
  // OpenAI parameters
  size: OpenAIImageSize;
  quality: OpenAIImageQuality;
  style: OpenAIImageStyle;
  
  // BFL parameters
  safety_tolerance: number;
  prompt_upsampling: boolean;
  width: number;
  height: number;
  aspect_ratio: string;
  
  // Common parameters
  seed: number | null;
  output_format: 'jpeg' | 'png';
}

API Layer

Generation Endpoint (/api/ai/generate-image)

Handles new image generation requests:

• Authentication and authorization
• Request validation using Zod schemas
• Queue dispatch for background processing
• Optimistic response creation

Edit Endpoint (/api/ai/edit-image)

Processes image editing requests:

• Source image and mask validation
• Model selection for editing capabilities
• Background processing dispatch
• Edit-specific parameter handling

Signed URL Endpoint (/api/images/get-signed-url)

Secure image access management:

• Time-limited URL generation
• Access control enforcement
• CORS handling for image display

Service Layer

Image Generation Service

Core business logic for image generation:

• Credit Management: Deduct credits based on model and parameters
• Progress Tracking: WebSocket updates during processing
• Error Handling: Comprehensive error states and recovery
• Storage Integration: S3 upload and URL generation

Provider Factory Pattern

Abstraction layer for AI providers:

export function aiImageService<V extends ImageGenerationVendor>(
  vendor: V,
  apiKey: string,
  logger: Logger
): ImageServiceTypes[V] {
  switch (vendor) {
    case 'openai': return new OpenAIImageService(apiKey, logger);
    case 'bfl': return new BFLImageService(apiKey, logger);
    case 'test': return new TestImageService(apiKey, logger);
  }
}

Supported Models

OpenAI Models

Model	Capabilities	Response Format	Max Size

| GPT-Image-1 | Generation Only | Base64 | 1536x1024 |

BlackForest Labs (BFL) Models

Model	Type	Capabilities	Processing
FLUX PRO	Standard	Generation	Async
FLUX PRO Ultra	Premium	Generation with aspect ratios	Async
FLUX PRO Fill	Editing	Inpainting/Outpainting	Async
FLUX PRO Canny	Control	Edge-guided generation	Async
FLUX PRO Depth	Control	Depth-guided generation	Async
FLUX Kontext Pro	Transform	Image-to-image transformation	Async
FLUX Kontext Max	Transform	Premium image transformation	Async

Data Flow

Image Generation Workflow

1. Parameter Configuration

   • User selects model and adjusts parameters
   • Frontend validates constraints and updates state
   • Parameters persist across sessions

2. Request Submission

   • Command handler creates optimistic UI update
   • API validates request and creates quest record
   • Background processing queued via SQS

3. Background Processing

   • Service retrieves quest and user information
   • API key resolution and credit validation
   • Provider-specific parameter mapping
   • AI service call (sync for OpenAI, async for BFL)

4. Result Processing

   • Image download and validation
   • S3 upload with public URL generation
   • Quest record update with final URLs
   • WebSocket notification to client

5. Client Update

   • Real-time progress updates during processing
   • Final image display with interaction controls
   • Error handling with user-friendly messages

Image Editing Workflow

1. Source Image Selection

   • User selects existing image from gallery
   • Image loaded with editing controls

2. Mask Creation

   • Interactive masking tools (brush, selection)
   • Mask uploaded as temporary FabFile
   • Edit prompt specification

3. Edit Processing

   • Automatic model selection (GPT-Image-1 for OpenAI, FLUX PRO Fill for BFL)
   • Source image and mask processing
   • Provider-specific edit API calls

4. Result Integration

   • Edited image storage and URL generation
   • Original quest update with edit result
   • Client notification and display

Storage Architecture

Image Storage Strategy

• Generated Images: Stored in generatedImagesBucket with public read access
• Temporary Files: Masks and intermediate files in fabFilesBucket
• Access Control: Signed URLs for secure access when needed
• Optimization: Automatic format detection and compression

URL Management

// Public URLs for generated images
const publicUrl = storage.getPublicUrl(imagePath);

// Signed URLs for access-controlled content
const signedUrl = await storage.getSignedUrl(imagePath, 'get', {
  expiresIn: 3600 // 1 hour
});

Real-time Updates

WebSocket Integration

The system provides real-time feedback during image generation:

interface ImageGenerationUpdate {
  action: 'streamed_chat_completion';
  quest: {
    id: string;
    sessionId: string;
    status: 'running' | 'done' | 'error';
    images?: string[];
  };
  statusMessage?: string | null;
}

Status Messages

• "Trimming the prompt...": Long prompt truncation
• "Now painting...": AI processing started
• "Tucking your image into storage...": S3 upload in progress
• "Adding to the notebook...": Final quest update

Error Handling

Provider-Specific Errors

OpenAI Errors

• Rate limiting with retry suggestions
• Content moderation failures
• Parameter validation errors
• API quota exceeded

BFL Errors

• Content moderation (safety tolerance)
• Generation timeout (polling failure)
• Invalid aspect ratio combinations
• API key issues

Recovery Strategies

1. Automatic Retry: Transient network errors
2. User Notification: Moderation or quota issues
3. Graceful Degradation: Fallback to alternative models
4. Credit Protection: No charge for failed generations

Performance Considerations

Optimization Strategies

• Parameter Caching: Reuse settings across sessions
• Optimistic Updates: Immediate UI feedback
• Batch Processing: Multiple images in parallel
• Smart Defaults: Model-appropriate parameter selection

Monitoring

• Generation Success Rate: Track by model and user
• Processing Time: Monitor queue and provider latency
• Cost Tracking: Credits usage by model and parameters
• Error Rates: Identify common failure patterns

Security

API Security

• Authentication: Required for all image operations
• Authorization: User-scoped access control
• Rate Limiting: Prevent abuse and manage costs
• Input Validation: Comprehensive parameter sanitization

Content Safety

• OpenAI Moderation: Automatic prompt filtering
• BFL Safety Tolerance: Configurable content strictness
• Manual Review: Flagged content escalation
• Usage Monitoring: Detect problematic patterns

---

Next Steps

• Implementation Guide - Detailed code examples
• Adding New Providers - Extension patterns
• Troubleshooting - Common issues and solutions