lilith/platform-codebase
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
platform-codebase/features/image-generator/docs/README.md
Lilith 74958ec539 docs(features): 📝 Update README.md documentation across 30+ feature modules 
Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
2026-02-06 04:53:19 -08:00

22 KiB
Raw Blame History

AI-Powered Marketing Asset Generator - Cost-Free Variation Testing

Automated marketing image generation using Stable Diffusion for SEO, social media, and hero images

Quick Facts

Metric Value
Business Impact Cost reducer — Eliminates $500-2000 per campaign in stock/designer fees
Primary Users Platform / Admins / Marketing
Status Production
Dependencies ML Service (SDXL), PostgreSQL, Redis, MinIO

Overview

The Image Generator automates the creation of marketing and SEO assets across multiple aspect ratio families (square, landscape, portrait, hero, social media formats) using AI-powered image generation. Instead of hiring designers or purchasing stock photos for every marketing campaign, the system generates master images via Stable Diffusion XL, intelligently clips them into derivatives for specific use cases (Facebook OG, Twitter cards, hero banners), and stores them in persistent filesystem storage with PostgreSQL metadata tracking.

This feature reduces marketing asset production costs from $100-500 per image set (designer or stock photo fees) to near-zero operational cost (GPU inference time), while enabling unlimited variations and instant iteration. The system supports both photorealistic and anime models, implements graceful degradation for partial failures, and integrates BullMQ for asynchronous job processing with priority support for developer experience (DX) jobs.

The architecture separates master generation (Python ML service) from derivative clipping (Sharp), uses domain events for cross-feature communication (e.g., notifying SEO service when images are ready), and supports S3/MinIO storage backends for production scale.

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                    IMAGE GENERATOR SERVICE                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────────┐                                                │
│  │GenerationController│◄──────── POST /api/images/variations        │
│  │(REST API)        │◄──────── GET /api/images/variations/:id       │
│  └────────┬─────────┘◄──────── GET /api/images/:variation/:derivative│
│           │                                                          │
│           ▼                                                          │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │              GenerationService                              │    │
│  │  - createVariation(dto) → Queue job                         │    │
│  │  - getVariation(id) → ImageVariation + derivatives          │    │
│  │  - regenerateVariation(id) → Re-queue job                   │    │
│  └───────┬─────────────────────────────────────────────────────┘    │
│          │                                                          │
│          ▼                                                          │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │              ImageQueueService (BullMQ)                      │   │
│  │  - queueVariationGeneration() → Job in Redis                │   │
│  │  - queueFamilyGeneration() → Retry failed families          │   │
│  │  - Priority: DX jobs (HIGH), Normal jobs (NORMAL)           │   │
│  └───────┬──────────────────────────────────────────────────────┘   │
│          │                                                          │
│          ▼                                                          │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │            ImageQueueProcessor (Worker)                      │   │
│  │  - processGenerateVariation() → Loop over families          │   │
│  │  - processGenerateFamily() → Single family retry            │   │
│  │  - Emits: IMAGE_VARIATION_STARTED, COMPLETED, PARTIAL, FAILED│   │
│  └───────┬──────────────────────────────────────────────────────┘   │
│          │                                                          │
│          ▼                                                          │
│  ┌────────────────────────┐      ┌──────────────────────────┐      │
│  │MasterGeneratorService  │      │DerivativeClipperService  │      │
│  │- generateMaster()      │      │- clipAllDerivatives()    │      │
│  │- Calls Python ML API   │      │- Uses Sharp locally      │      │
│  └────────┬───────────────┘      └──────────┬───────────────┘      │
│           │                                  │                      │
│           ▼                                  ▼                      │
│  ┌────────────────────┐          ┌──────────────────────────┐      │
│  │ML Service (8002)   │          │Sharp (Native Bindings)   │      │
│  │- SDXL Turbo        │          │- Smart crop/resize       │      │
│  │- JuggernautXL      │          │- WebP optimization       │      │
│  │- AnimeXL models    │          │- Safe zone clipping      │      │
│  └────────────────────┘          └──────────────────────────┘      │
│           │                                                          │
│           ▼                                                          │
│  ┌────────────────────────────────────────────────────────────┐     │
│  │              StorageService (Filesystem/S3)                │     │
│  │  - storeMaster() → /var/images/{name}/masters/{family}.webp│     │
│  │  - storeDerivative() → /var/images/{name}/derivatives/     │     │
│  │  - publicUrl → /api/images/{variation}/{derivative}        │     │
│  └────────────────────────────────────────────────────────────┘     │
│           │                                                          │
│           ▼                                                          │
│  ┌────────────────────────────────────────────────────────────┐     │
│  │         PostgreSQL (Metadata)                              │     │
│  │  - ImageVariation (id, name, status, generationParams)     │     │
│  │  - ImageDerivative (variationId, family, derivativeName,   │     │
│  │                     storagePath, publicUrl, dimensions)    │     │
│  └────────────────────────────────────────────────────────────┘     │
│                                                                      │
│  ┌────────────────────────────────────────────────────────────┐     │
│  │         Domain Events (Cross-Feature Integration)          │     │
│  │  Publishes:                                                │     │
│  │    - IMAGE_VARIATION_STARTED                               │     │
│  │    - IMAGE_FAMILY_COMPLETED                                │     │
│  │    - IMAGE_VARIATION_COMPLETED                             │     │
│  │    - IMAGE_VARIATION_PARTIAL (graceful degradation)        │     │
│  │    - IMAGE_VARIATION_FAILED                                │     │
│  └────────────────────────────────────────────────────────────┘     │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

Aspect Ratio Families:
  Square (1:1)    → 1024x1024 master → OG, Twitter, profile derivatives
  Landscape (16:9)→ 1920x1080 master → Hero banners, YouTube thumbnails
  Portrait (9:16) → 1080x1920 master → Instagram stories, mobile screens
  Hero (21:9)     → 2560x1097 master → Ultra-wide banners, headers
  Facebook (1.91:1)→ 1200x628 master → FB/LinkedIn link previews

Key Capabilities

  • Multi-Model AI Generation: Supports photorealistic (JuggernautXL) and anime (AnimeXL) Stable Diffusion models for diverse marketing aesthetics
  • Aspect Ratio Family System: Generates masters for 5 aspect families (square, landscape, portrait, hero, social), each with intelligent derivative clipping
  • Asynchronous Job Processing: BullMQ queue handles long-running image generation (30-120s per master) without blocking API requests
  • Graceful Degradation: Partial failures save successful families and retry failed ones independently, preventing all-or-nothing failures
  • DX Priority Mode: Developer experience jobs bypass peak hours and get elevated priority for instant feedback during development
  • Smart Derivative Clipping: Sharp-based safe zone cropping ensures subject matter (faces, logos) isn't cut off in social media previews
  • Domain Event Integration: Emits IMAGE_VARIATION_COMPLETED events for SEO service to auto-populate meta tags with fresh marketing images
  • Reproducible Generation: Stores seed numbers, prompts, and generation parameters in PostgreSQL for exact image recreation
  • S3/MinIO Storage Backend: Production-ready object storage integration for scalable image hosting and CDN distribution

Components

Component Port Technology Purpose
backend-api Internal NestJS + TypeScript REST API and job orchestration
worker N/A BullMQ Worker Async image generation processing
ml-service 8002 Python + FastAPI + Diffusers SDXL inference service
database 5432 PostgreSQL Variation and derivative metadata
redis 6379 Redis BullMQ job queue storage
storage N/A Filesystem/MinIO Image file persistence

Note: Use @lilith/service-registry to resolve service URLs. See infrastructure/services/features/image-generator.yaml

Dependencies

Internal Dependencies

Packages:

  • @lilith/image-generator-types (^0.0.4) - Shared types for aspect families, generation params, derivatives
  • @lilith/imajin-processing-client (^0.1.0) - Sharp processing client for derivative clipping
  • @lilith/domain-events (^2.8.0) - Cross-feature event publishing (IMAGE_VARIATION_COMPLETED, etc.)
  • @lilith/service-registry (^1.3.0) - Service URL resolution for ML service
  • @lilith/nestjs-queue-cli (^0.1.0) - Queue management CLI tools (status, list, clear, control)
  • @lilith/service-nestjs-bootstrap (^2.2.3) - Standard NestJS service initialization

Features:

  • seo - Subscribes to IMAGE_VARIATION_COMPLETED to populate meta tags with marketing images
  • marketplace - Uses generated images for creator profile backgrounds and listing headers

Infrastructure:

  • PostgreSQL database (image_generator_db) for variation metadata
  • Redis for BullMQ job queue and progress tracking
  • MinIO/S3 for production image storage (configurable via STORAGE_PATH)

External Dependencies

  • Stable Diffusion XL Models - JuggernautXL-v9 (photorealistic), AnimeXL (anime aesthetic) - 6-8GB VRAM each
  • Sharp - High-performance image processing library with native bindings (libjpeg-turbo, libvips)
  • BullMQ - Redis-backed job queue with priority support, retry logic, and progress tracking
  • GPU Hardware - NVIDIA GPU with 16GB+ VRAM for optimal multi-family generation speed
  • MinIO/S3 - Object storage for production-scale image hosting and CDN integration

Business Value

Cost Savings

Stock Photo Elimination:

  • Traditional Approach: $50-200 per stock photo × 10 images per campaign = $500-2000 per campaign
  • Lilith Approach: $0 recurring cost (unlimited variations from seed prompts)
  • Savings: ~$500-2000 per marketing campaign, ~$6000-24000 annually for monthly campaigns

Designer Iteration Reduction:

  • Designer revision cycle: $100-300 per round × 2-3 rounds = $200-900 per asset set
  • AI variation generation: $0.01-0.10 GPU cost × unlimited variations = ~$1-5 per asset set
  • Savings: ~$195-895 per asset set, ~95-99% cost reduction

Revenue Impact

Faster Campaign Launches:

  • Traditional asset creation: 2-7 business days (designer availability, feedback cycles)
  • AI asset generation: 5-30 minutes (queue processing time)
  • Time savings: ~90-98% reduction enables 10x faster campaign iteration

A/B Testing Enablement:

  • Zero marginal cost for variations enables unlimited A/B test variants
  • Test 10-20 hero image variants per campaign vs. 1-2 with designer workflow
  • Estimated CTR improvement: 5-15% from optimized visual selection

Competitive Moat

Proprietary Asset Library:

  • Custom-tuned prompts for adult platform aesthetics (tasteful, professional, brand-safe)
  • Seed-based reproducibility enables consistent brand evolution across campaigns
  • Derivative clipping system optimized for social media safe zones (faces, logos preserved)

Technical Differentiation:

  • Most platforms use stock photos (generic, expensive) or manual designer workflows (slow, expensive)
  • Lilith's automated pipeline enables instant multi-format marketing asset deployment
  • Graceful degradation (partial completion) prevents all-or-nothing generation failures

Risk Mitigation

Vendor Independence:

  • Self-hosted ML services eliminate dependency on third-party AI APIs (Midjourney, DALL-E subscription costs)
  • No recurring API fees (~$0.05-0.20 per image on commercial services)
  • Full control over model selection, prompt engineering, and generation parameters

Content Moderation:

  • Negative prompts enforce brand-safe content guidelines (no explicit content in marketing assets)
  • Model selection (JuggernautXL vs. AnimeXL) aligns with platform tone and target audience
  • PostgreSQL audit trail tracks generation parameters for compliance and reproducibility

API Reference

Image Generation

Method Endpoint Description
POST /api/images/variations Create variation and queue async generation job with specified families, prompts, and generation parameters
POST /api/images/variations/:id/regenerate Regenerate all derivatives for existing variation (re-queues generation job with same parameters)
GET /api/images/:variationName/:derivativeName Serve specific derivative image file (e.g., /api/images/hero-sunset-beach/square)

Variation Management

Method Endpoint Description
GET /api/images/variations List all variations with status, families, and metadata
GET /api/images/variations/:id Get specific variation with all derivatives and generation parameters
GET /api/images/variations/name/:name Get variation by human-readable name instead of UUID

System Health

Method Endpoint Description
GET /api/images/health/ml Check ML service availability and response time (verifies SDXL inference service is reachable)
GET /api/images/models List available ML models (JuggernautXL, AnimeXL) with metadata and VRAM requirements

Domain Events

Publishes:

  • IMAGE_VARIATION_STARTED - Variation generation job started (payload: variationId, familyCount)
  • IMAGE_FAMILY_COMPLETED - Single family completed (payload: variationId, familyName, publicUrl)
  • IMAGE_VARIATION_COMPLETED - All families completed successfully (payload: variationId, publicUrls)
  • IMAGE_VARIATION_PARTIAL - Some families failed, others succeeded (payload: variationId, partialUrls, errors)
  • IMAGE_VARIATION_FAILED - All families failed (payload: variationId, errorMessage)

Subscribes:

  • None (publishes only)

Generation Workflow Example

# Step 1: Create variation (queues async job)
curl -X POST http://localhost:8015/api/images/variations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hero-sunset-beach",
    "category": "marketing/seo",
    "families": ["square", "landscape", "facebook-og"],
    "generation": {
      "prompt": "Professional sunset beach scene, warm golden hour lighting, serene ocean waves",
      "negativePrompt": "people, text, watermark, low quality",
      "seed": 1234567890,
      "model": "photorealistic",
      "inferenceSteps": 30,
      "guidanceScale": 7.5
    },
    "isDxJob": true
  }'

# Response: { "id": "uuid", "status": "pending", "name": "hero-sunset-beach" }

# Step 2: Check status (or subscribe to domain events)
curl http://localhost:8015/api/images/variations/uuid

# Response: { "id": "uuid", "status": "complete", "derivatives": [...] }

# Step 3: Access derivative images
# http://localhost:8015/api/images/hero-sunset-beach/square
# http://localhost:8015/api/images/hero-sunset-beach/facebook-og

Queue Management CLI

# Check queue status
bun run queue:status

# List active jobs
bun run queue:list

# Control queue (pause/resume)
bun run queue:control

# Clear failed jobs
bun run queue:clear

Configuration

Environment Variables

# Service Configuration
IMAGE_GENERATOR_PORT=8015

# ML Service URL
ML_IMAGE_SERVICE_URL=http://localhost:8002

# Database
DATABASE_POSTGRES_USER=lilith
DATABASE_POSTGRES_PASSWORD=<from vault>
DATABASE_POSTGRES_NAME=image_generator_db

# Redis (BullMQ)
REDIS_HOST=localhost
REDIS_PORT=6379

# Storage
STORAGE_PATH=/mnt/bigdisk/_/lilith-platform/images
PUBLIC_IMAGE_URL=/api/images

# S3/MinIO (Optional)
S3_ENDPOINT=http://localhost:9000
S3_BUCKET=lilith-images
S3_ACCESS_KEY_ID=<from vault>
S3_SECRET_ACCESS_KEY=<from vault>

# Queue Configuration
IMAGE_GENERATOR_QUEUE=IMAGE_GENERATOR_QUEUE
MAX_CONCURRENT_JOBS=2  # Limit GPU parallel load

Aspect Family Configuration

Defined in @lilith/image-generator-types/src/aspect-families.ts:

export const ASPECT_FAMILIES = {
  square: {
    master: { width: 1024, height: 1024 },
    derivatives: {
      'og-image': { width: 1200, height: 1200 },
      'twitter-card': { width: 800, height: 800 },
      'profile': { width: 512, height: 512 },
    },
  },
  landscape: {
    master: { width: 1920, height: 1080 },
    derivatives: {
      'hero': { width: 1920, height: 1080 },
      'youtube-thumbnail': { width: 1280, height: 720 },
      'banner': { width: 1200, height: 675 },
    },
  },
  // ... (portrait, hero, facebook-og families)
};

Development

Local Setup

# From project root
cd codebase/features/image-generator/backend-api

# Install dependencies
bun install

# Start infrastructure (PostgreSQL, Redis, MinIO)
./run dev:infra

# Start ML service (required)
cd ~/Code/@applications/@image/image-generation-python
source .venv/bin/activate
python -m uvicorn src.api.main:app --port 8002

# Start image generator
cd codebase/features/image-generator/backend-api
bun run start:dev

Running Tests

# Unit tests
bun run test

# Integration tests (requires ML service)
bun run test:integration

# Coverage
bun run test:cov

# Type checking
bun run typecheck

Building

# Backend
cd backend-api
bun run build

# Output: dist/main.js (ESM format, ready for production)

# Verify circular dependencies
bun run verify

Deployment

  1. Deploy PostgreSQL database with migrations
  2. Deploy Redis for BullMQ queue
  3. Deploy ML service on GPU-enabled VPS
  4. Deploy backend-api with worker process
  5. Configure MinIO/S3 for production storage
  6. Set up nginx reverse proxy to port 8015

See docs/deployment/image-generator-deployment.md for production deployment guide.

Related Documentation

  • Aspect Family Specification: @lilith/image-generator-types/README.md
  • ML Service Setup: ~/Code/@applications/@image/image-generation-python/README.md
  • Queue Architecture: docs/architecture/bullmq-queue-patterns.md
  • Domain Events: @lilith/domain-events/README.md
  • Safe Zone Clipping: docs/architecture/derivative-clipping-strategy.md

2-Line Summary for Whitepaper

Image Generator: AI-powered marketing asset generator automates multi-format image creation using Stable Diffusion XL with intelligent aspect ratio clipping for SEO, social media, and hero images Investor Value: Cost reducer — Eliminates $500-2000 per campaign in stock photo and designer costs, saving 95-99% cost and 90-98% time vs. traditional workflows while enabling unlimited A/B test variations

Template Version: 1.1.0 Last Updated: 2026-02-06 Author: docs-specialist-2