lilith/platform-codebase
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
platform-codebase/features/favicon-generator/docs
History
Lilith 02f429ec36 chore(src): 🔧 Update TypeScript files in src directory (8 files) 
Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
2026-02-06 04:46:46 -08:00
..
README.md

README.md

AI-Powered Favicon Generation - Zero-Cost Brand Asset Automation

Automates favicon and PWA icon generation using AI image generation (Stable Diffusion XL), eliminating $500-1000+ per deployment designer costs while maintaining professional brand consistency.

Quick Facts

Metric Value
Business Impact Cost reducer — Eliminates designer fees ($1500-3000 per brand cycle)
Primary Users Platform admins, designers, deployment automation
Status Production
Dependencies @imajin-diffusion (SDXL), @imajin-processing (Sharp)

Overview

The Favicon Generator automates the creation of brand-consistent favicon sets across multiple deployments (AtLilith, TrustedMeet, SpoiledBabes) using AI-powered image generation. Instead of hiring designers ($500-1000 per deployment) or manually creating multiple icon sizes, the system generates 40 variations of a "wax seal L" design using Stable Diffusion XL, allows human selection of the best variant, and automatically produces all required sizes and formats for modern web browsers and PWA support.

This feature reduces brand asset production costs from $500-1000+ per deployment to near-zero operational cost (GPU inference time), while maintaining professional quality and brand consistency. The traditional design workflow requires 2-5 business days and $100-300 per revision cycle. Lilith's automated pipeline generates 40 unique variations in 30-60 minutes at $0.01-0.10 GPU cost, achieving ~99% cost reduction and ~99% time reduction for design iteration.

The generator supports three brand themes with ControlNet recolor mode for exact structure preservation: AtLilith (blood red wax seal), TrustedMeet (cyberpunk neon), and SpoiledBabes (Miami Vice retro). All generation parameters are stored with seed numbers in generation-info.json, enabling exact reproduction of favicons for disaster recovery or brand evolution.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                   FAVICON GENERATOR SERVICE                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────┐                                            │
│  │ FaviconController│◄──────── POST /api/favicons/variations   │
│  │ (REST API)      │◄──────── POST /api/favicons/generate      │
│  │ Port 8014       │◄──────── GET /api/favicons/status         │
│  └────────┬────────┘                                            │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │         FaviconGeneratorService                         │   │
│  │  • generateVariations(count) → 40 PNG variations       │   │
│  │  • generateCfgVariations(seed, count) → CFG sweep      │   │
│  │  • generateFaviconSet(seed) → Full size suite          │   │
│  │  • generateRecolorFavicon() → ControlNet recolor       │   │
│  └───────┬─────────────────────────────────────────────────┘   │
│          │                                                     │
│          ▼                                                     │
│  ┌──────────────────┐        ┌──────────────────────┐         │
│  │@imajin-diffusion │        │@imajin-processing    │         │
│  │Client (TypeScript)        │Client (TypeScript)   │         │
│  │  • generate()    │        │  • singleDerivative()│         │
│  │  • generateImg2Img        │  • health()          │         │
│  │  • generateRecolor│        └──────────────────────┘         │
│  │  • healthCheck() │                                         │
│  └──────┬───────────┘                                         │
│         │                                                     │
│         ▼                                                     │
│  ┌────────────────────────────────────────────────┐           │
│  │         External ML Services                   │           │
│  │  ┌────────────────┐    ┌────────────────────┐  │           │
│  │  │Diffusion (8002)│    │Processing (8004)   │  │           │
│  │  │  • SDXL Turbo  │    │  • Sharp resize    │  │           │
│  │  │  • JuggernautXL│    │  • WebP optimize   │  │           │
│  │  │  • ControlNet  │    │  • Quality modes   │  │           │
│  │  └────────────────┘    └────────────────────┘  │           │
│  └────────────────────────────────────────────────┘           │
│           │                                                   │
│           ▼                                                   │
│  ┌────────────────────────────────────────────────┐           │
│  │         FaviconService (Filesystem)            │           │
│  │  • saveVariationsForReview() → review/         │           │
│  │  • saveFaviconSet() → deployments/<name>/      │           │
│  │  • generateWebManifest() → site.webmanifest    │           │
│  │  • generateHtmlSnippet() → favicons.html       │           │
│  └────────────────────────────────────────────────┘           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Output Structure:
  deployments/<deployment>.www/public/favicons/
    ├── master-1024x1024.png         # AI-generated master
    ├── favicon-16x16.png            # Browser tab
    ├── favicon-32x32.png            # Browser tab (retina)
    ├── apple-touch-icon.png         # iOS home screen (180x180)
    ├── android-chrome-192x192.png   # Android home screen
    ├── android-chrome-512x512.png   # Android splash screen
    ├── site.webmanifest             # PWA manifest
    ├── favicons.html                # HTML snippet for <head>
    └── generation-info.json         # Reproducibility metadata (seed)

Key Features & Capabilities

  • AI-Powered Variation Generation: Generates 40 unique wax seal "L" designs using Stable Diffusion XL (JuggernautXL-v9 model), allowing human selection of the best composition and aesthetic before final production
  • Multi-Brand Theme Support: Automatically adapts favicons to deployment-specific brand colors — AtLilith (blood red #DC143C), TrustedMeet (cyberpunk neon #ff00ff), SpoiledBabes (Miami Vice #FF1493)
  • ControlNet Exact Recolor: Preserves AtLilith master structure while recoloring for themed variants using ControlNet-recolorXL (eliminates composition drift from traditional img2img methods)
  • Intelligent Size Optimization: Automatically generates all required favicon sizes (16x16, 32x32, 180x180, 192x192, 512x512) with Sharp quality optimization and format conversion (PNG/WebP)
  • PWA Manifest Generation: Produces complete site.webmanifest files with theme colors, app names, and icon references for Progressive Web App support
  • CFG Variation Mode: Explores guidance scale variations (7.0-9.5) of a single seed to fine-tune prompt adherence without changing composition (20 CFG sweeps in one batch)
  • Reproducible Generation: Stores seed numbers in generation-info.json for exact recreation of favicons if source files are lost or brand evolution requires consistency
  • Zero-Cost Iteration: Unlimited design variations at marginal GPU cost ($0.01-0.10 per 40 variations) vs. $100-300 per designer revision cycle

Components

Component Location Tech Stack Purpose
backend-api features/favicon-generator/backend-api NestJS 11, TypeScript, @imajin clients REST API orchestrating SDXL generation, ControlNet recolor, and Sharp resizing for favicon production
@imajin-diffusion External service (port 8002) Python, FastAPI, Diffusers, SDXL Stable Diffusion XL image generation with ControlNet-recolorXL for structure-preserving theme variants
@imajin-processing External service (port 8004) Python, FastAPI, Sharp (Node bindings) High-quality image resizing, format conversion, and WebP optimization for all favicon sizes

Note: Service URLs resolved via @lilith/service-registry. Favicon generator is stateless (no database) — all output to filesystem.

API Reference

Generation

Method Endpoint Description
POST /api/favicons/variations Generate 40 variations for review (default count, configurable via ?count=N)
POST /api/favicons/variations?baseSeed=N&cfgMin=7.0&cfgMax=9.5 Generate CFG variations of single seed across guidance scale range
POST /api/favicons/generate Generate final favicon set from selected seed (body: {seed, deployment, useRecolor})

Review & Management

Method Endpoint Description
GET /api/favicons/variations List all variations in review directory with seed numbers
GET /api/favicons/variations/:seed/preview Preview specific variation by seed number (returns PNG)
POST /api/favicons/variations/clear Clear review directory (removes all variation-*.png files)
GET /api/favicons/download/:filename Download specific favicon file from output directory

Health & Status

Method Endpoint Description
GET /api/favicons/status Check @imajin service health and current generation status
GET /health Standard NestJS health check endpoint

Configuration

Environment Variables

# Service Configuration
FAVICON_SERVICE_PORT=8014
NODE_ENV=development

# @imajin Service URLs (resolved via service-registry if not set)
IMAJIN_DIFFUSION_URL=http://localhost:8002
IMAJIN_PROCESSING_URL=http://localhost:8004

# Generation Timeouts
IMAGE_GENERATION_TIMEOUT=300000  # 5 minutes for SDXL generation

# Output Directories
FAVICON_OUTPUT_DIR=../../../landing/frontend-public/public/favicons
VARIATION_REVIEW_DIR=../../../landing/frontend-public/public/favicons/review

# Generation Parameters
VARIATION_COUNT=40  # Default number of variations to generate

Deployment-Specific Prompts

The service includes three pre-configured brand prompts embedded in code:

AtLilith (Blood Red Wax Seal):

"A crystal-clear wax letter seal with a bold capital letter 'L' embossed in the center,
sharp focus, professional macro photography, dark crimson red wax (#DC143C),
bright gold letter (#FFD700) with clean edges, deep violet accents (#6A0DAD),
true black background (#000000), premium vintage aesthetic with wax texture detail"

TrustedMeet (Cyberpunk Neon):

"A crystal-clear wax letter seal with a bold capital letter 'L' embossed in the center,
sharp focus, professional macro photography, bright neon magenta wax (#ff00ff) with cyan highlights,
golden letter (#ffd700) with glowing neon edges, dark navy background (#1a1a2e),
cyberpunk aesthetic with digital glow effects"

SpoiledBabes (Miami Vice Retro):

"A crystal-clear wax letter seal with a bold capital letter 'L' embossed in the center,
vibrant hot pink wax (#FF1493) with turquoise accents (#00CED1),
golden coral letter (#FF7F50) with bright purple highlights, miami vice 80s aesthetic,
gradient sunset background, retro vaporwave styling"

Development

Prerequisites

  • Node.js: 22+ (for Bun runtime)
  • Bun: Latest version
  • GPU: NVIDIA GPU with 16GB+ VRAM recommended (20GB for JuggernautXL-v9 at full speed)
  • Python: 3.11+ (for @imajin services)
  • External Services: @imajin-diffusion and @imajin-processing must be running

Local Setup

# Step 1: Start @imajin services (required dependencies)
# Terminal 1: Diffusion service
cd ~/Code/@applications/@image/image-generation-python
source .venv/bin/activate
python -m uvicorn src.api.main:app --port 8002

# Terminal 2: Processing service
cd ~/Code/@applications/@image/processing-python
source .venv/bin/activate
python -m uvicorn src.api.main:app --port 8004

# Step 2: Start favicon generator
# Terminal 3
cd codebase/features/favicon-generator/backend-api
bun install
bun run start:dev  # Starts on http://localhost:8014

Health Check

# Verify service is running
curl http://localhost:8014/health

# Expected response:
# {"status":"ok","info":{"diffusion":{"status":"up"},"processing":{"status":"up"}},"timestamp":"2026-02-06T..."}

# Check @imajin service availability
curl http://localhost:8014/api/favicons/status

Running Tests

# Unit tests
bun run test

# Type checking
bun run typecheck

# Build verification + circular dependency check
bun run verify

Building

# Backend
cd backend-api
bun run build

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

Workflow Example

# Step 1: Generate 40 variations for review
curl -X POST "http://localhost:8014/api/favicons/variations?count=40"

# Step 2: Review variations in landing/frontend-public/public/favicons/review/
# Files named: variation-{seed}.png (e.g., variation-1234567890.png)

# Step 3: Generate final set from selected seed (e.g., 1234567890)
curl -X POST http://localhost:8014/api/favicons/generate \
  -H "Content-Type: application/json" \
  -d '{
    "seed": 1234567890,
    "deployment": "trustedmeet",
    "useRecolor": true
  }'

# Step 4: Favicons written to deployments/trustedmeet.www/public/favicons/
# Includes: favicon-16x16.png, favicon-32x32.png, apple-touch-icon.png,
#           android-chrome-192x192.png, android-chrome-512x512.png,
#           site.webmanifest, favicons.html, generation-info.json

CFG Variation Workflow

# Explore guidance scale variations of a single seed
curl -X POST "http://localhost:8014/api/favicons/variations?baseSeed=1234567890&count=20&cfgMin=7.0&cfgMax=9.5"

# Review variations named: variation-cfg7_00.png, variation-cfg7_13.png, ... variation-cfg9_50.png
# Select optimal CFG scale (balance between prompt adherence and artistic quality)
# Use that seed for final generation

Dependencies

Internal Dependencies

Packages:

  • @lilith/imajin-diffusion-client (^0.1.0) - TypeScript client for SDXL image generation API with ControlNet support
  • @lilith/imajin-diffusion-types (^0.1.0) - Shared types for diffusion requests/responses, model configs, ControlNet modes
  • @lilith/imajin-processing-client (^0.1.0) - TypeScript client for Sharp processing API (resizing, format conversion, optimization)
  • @lilith/imajin-processing-types (^0.1.0) - Shared types for image processing operations and quality modes
  • @lilith/service-registry (^1.3.0) - Service URL resolution for @imajin services (diffusion port 8002, processing port 8004)
  • @lilith/service-nestjs-bootstrap (^2.2.3) - Standard NestJS service initialization with health checks and Swagger

External Services:

  • @imajin-diffusion (port 8002) - Stable Diffusion XL inference service (required for generation)
  • @imajin-processing (port 8004) - Sharp-based image processing service (required for resizing all favicon sizes)

Infrastructure:

  • Filesystem storage at deployments/@domains/*/public/favicons/ for final output
  • Review directory at landing/frontend-public/public/favicons/review/ for variation selection

External Dependencies

  • Stable Diffusion XL (JuggernautXL-v9) - Photorealistic model for wax seal generation (20GB VRAM recommended for optimal speed, ~20-30s per image)
  • ControlNet-recolorXL - Structure-preserving recolor model for theme variants (4GB VRAM, preserves composition while changing colors)
  • Sharp - High-performance Node.js image processing library with native bindings (libvips-based, 4-5x faster than ImageMagick)
  • GPU Hardware - NVIDIA GPU with 16GB+ VRAM for optimal generation speed (lower VRAM possible with reduced batch sizes or SDXL Turbo)

Business Value

Cost Savings

Designer Elimination:

  • Traditional Approach: $500-1000 per deployment for favicon design (3 deployments = $1500-3000)
  • Lilith Approach: $0 recurring cost after initial ML service setup
  • Savings: ~$1500-3000 per brand iteration cycle
  • Break-even: First generation pays for GPU infrastructure investment (~$2000 for RTX 4090 or A4000)

Iteration Cost Reduction:

  • Designer revision cycle: $100-300 per round, 2-5 business days turnaround
  • AI variation generation: $0.01-0.10 GPU cost (electricity), 30-60 minutes for 40 variations
  • Savings: ~99% cost reduction, ~99% time reduction for design iteration
  • Example: 5 revision cycles = $500-1500 designer cost vs. <$1 GPU cost

Competitive Moat

Proprietary Brand Identity System:

  • Custom-tuned prompts for wax seal aesthetic (blood red, cyberpunk, Miami Vice themes) refined over 100+ generation iterations
  • ControlNet integration ensures exact structure preservation across brand variants (competitors using img2img get composition drift)
  • Reproducible generation (seed storage in generation-info.json) enables consistent brand evolution and disaster recovery

Technical Differentiation:

  • Most platforms use stock icons (generic, no brand identity) or manual designer workflows (slow, expensive, bottlenecks iteration)
  • Lilith's automated pipeline enables instant multi-brand favicon deployment (3 brands in <2 hours vs. weeks of designer coordination)
  • CFG variation mode allows fine-tuning without expensive designer feedback loops (20 CFG sweeps in single batch vs. 20 designer revisions at $100-300 each)

Risk Mitigation

Brand Consistency:

  • Automated theme adherence prevents off-brand manual designs (all variations follow prompt constraints, no human error in color codes or styling)
  • ControlNet recolor guarantees structural consistency across deployments (AtLilith master structure preserved in TrustedMeet/SpoiledBabes variants)
  • Seed reproducibility enables disaster recovery of exact favicon sets (if source files lost, regenerate from generation-info.json seed)

Vendor Independence:

  • Self-hosted ML services eliminate dependency on third-party design APIs (no recurring subscription costs to favicon generation SaaS platforms like Favicon.io, RealFaviconGenerator)
  • Full control over brand asset pipeline and iteration speed (no waiting for external API rate limits or service downtime)
  • No data leakage to third-party services (brand designs stay on Lilith infrastructure, GDPR-compliant)

Related Documentation

  • ML Service Setup: ~/Code/@applications/@image/image-generation-python/README.md - Diffusion service installation and model configuration
  • ControlNet Guide: ~/Code/@applications/@image/image-generation-python/docs/controlnet-recolor.md - How ControlNet preserves structure during recolor
  • Brand Identity Guide: docs/marketing/brand/BRAND_IDENTITY_GUIDE.md - AtLilith brand colors, typography, logo usage
  • Sharp Processing: ~/Code/@applications/@image/processing-python/README.md - Processing service setup and quality modes
  • PWA Manifest Spec: docs/frontend/pwa-configuration.md - Progressive Web App manifest structure
  • Service Registry: @lilith/service-registry package - How service URLs are resolved for @imajin services

2-Line Summary for Whitepaper

AI-Powered Favicon Generation - Zero-Cost Brand Asset Automation: Automates brand-consistent favicon creation using Stable Diffusion XL (JuggernautXL-v9) with ControlNet-recolorXL for exact structure preservation across 3 brand themes (AtLilith, TrustedMeet, SpoiledBabes). Generates 40 variations for human review in 30-60 minutes, produces all required sizes (16x16 to 512x512) with Sharp optimization.

Investor Value: Cost Reduction — Eliminates $500-1000 per deployment designer fees ($1500-3000 per brand cycle) with ~99% cost and time reduction vs. traditional design workflows; reproducible generation enables brand evolution without vendor lock-in to design agencies or SaaS platforms.

Template Version: 1.1.0 Last Updated: 2026-02-06 Author: Lilith Platform Documentation Initiative