lilith/platform-codebase
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
platform-codebase/features/favicon-generator
History
…
..
backend-api
docs
README.md

README.md

Backend Favicon Generator

NestJS service for generating platform favicons using @imajin AI services.

Purpose

  1. Generate Brand Favicons: Wax seal "L" design for AtLilith.com
  2. Reference Implementation: Example of @imajin client consumption
  3. Demonstrates Patterns:
    • External service health checks (OnModuleInit)
    • Dynamic URL resolution via config
    • Base64 ↔ Buffer conversions
    • Batch variation generation for design review

Brand Design

Based on docs/marketing/brand/BRAND_IDENTITY_GUIDE.md:

  • Symbol: Letter "L" as old-timey wax letter seal
  • Primary Color: Blood Red (#DC143C)
  • Accents: Deep Violet (#6A0DAD), True Black (#000000), Bright Gold (#FFD700)
  • Style: Premium vintage aesthetic with wax texture detail

Workflow

Step 1: Generate Variations for Review

# Generate 40 variations (default)
curl -X POST http://localhost:3099/api/favicons/variations

# Generate custom count
curl -X POST "http://localhost:3099/api/favicons/variations?count=20"

This creates 40 unique wax seal designs in public/favicons/review/, each named with its seed: variation-{seed}.png

Step 2: Review and Select

# List all variations
curl http://localhost:3099/api/favicons/variations

# Preview specific variation
curl http://localhost:3099/api/favicons/variations/1234567890/preview -o preview.png

# Or open the review directory in file manager
open codebase/features/landing/frontend-public/public/favicons/review/

Step 3: Generate Final Set

# Generate final favicon set with selected seed
curl -X POST http://localhost:3099/api/favicons/generate \
  -H "Content-Type: application/json" \
  -d '{"seed": 1234567890}'

API Endpoints

Endpoint Method Description
/api/favicons/variations POST Generate variations for review
/api/favicons/variations GET List all variations
/api/favicons/variations/:seed/preview GET Preview specific variation
/api/favicons/variations/clear POST Clear review directory
/api/favicons/generate POST Generate final set from seed
/api/favicons/status GET Check service health
/api/favicons/download/:filename GET Download individual file
/health GET Standard health check

Generated Files

Review Directory

codebase/features/landing/frontend-public/public/favicons/review/

  • variation-{seed}.png × 40 (or custom count)

Final Output

codebase/features/landing/frontend-public/public/favicons/

  • favicon-16x16.png (Browser tabs)
  • favicon-32x32.png (Browser tabs HD)
  • apple-touch-icon.png (iOS 180×180)
  • android-chrome-192x192.png (Android)
  • android-chrome-512x512.png (Android splash)
  • site.webmanifest (PWA manifest)
  • favicons.html (HTML snippet)
  • master-1024x1024.png (Reference)
  • generation-info.json (Seed for reproducibility)

Configuration

.env options:

PORT=3099
NODE_ENV=development

# Override @imajin service URLs
IMAJIN_DIFFUSION_URL=http://localhost:8002
IMAJIN_PROCESSING_URL=http://localhost:8005

# Override directories
FAVICON_OUTPUT_DIR=../landing/frontend-public/public/favicons
VARIATION_REVIEW_DIR=../landing/frontend-public/public/favicons/review

# Generation options
VARIATION_COUNT=40
IMAGE_GENERATION_TIMEOUT=300000

Starting Services

Required Services

  1. imajin-diffusion (port 8002) - SDXL image generation
  2. imajin-processing (port 8005) - Sharp-based resizing
# Terminal 1: Start imajin services
cd ~/Code/@applications/@imajin
./run dev

# Terminal 2: Start this service
cd codebase/features/favicon-generator/backend-api
pnpm install
pnpm start:dev

Health Check

curl http://localhost:3099/health

@imajin Client Patterns

Health Checks at Startup

async onModuleInit(): Promise<void> {
  try {
    const health = await this.client.healthCheck();
    this.available = health.status === 'healthy';
  } catch {
    this.logger.warn('Service not available');
  }
}

Base64 Conversions

// Input: Buffer → Base64
const base64 = buffer.toString('base64');
const result = await client.process(base64);

// Output: Base64 → Buffer
const outputBuffer = Buffer.from(result.data, 'base64');

Dependencies

  • @lilith/imajin-diffusion-client - SDXL image generation
  • @lilith/imajin-processing-client - Sharp-based resizing
  • @lilith/service-nestjs-bootstrap - Standard NestJS bootstrap
  • @lilith/nestjs-health - Health check endpoints

Testing

# Run unit tests
pnpm test

# Verify circular dependencies (requires build)
pnpm verify

# Type check
pnpm typecheck