imajin/docs/services

Services & Components

The Imajin platform consists of a main orchestrator service, specialized ML services, and client libraries.

Overview

Component	Type	Stack	Purpose
imajin	Service	Python/FastAPI	Main entry point - orchestrates all services
imajin-app	Library	React/TypeScript	Pipeline orchestration, plugin UI
imajin-prompt	Service	Python/FastAPI	LLM-powered prompt generation
imajin-diffusion	Service	Python/FastAPI	Diffusion model image generation
imajin-processing	Service	NestJS/TypeScript	Image post-processing

Architecture

graph TB
    subgraph Consumers
        SEO[lilith-platform SEO]
        DESKTOP[desktop-chat-app]
        ADMIN[platform-admin]
    end

    subgraph "Main Entry Point"
        IMAJIN[imajin :8080]
    end

    subgraph "ML Services"
        PROMPT[imajin-prompt :8003]
        DIFFUSION[imajin-diffusion :8002]
        PROCESSING[imajin-processing :8004]
    end

    SEO -->|POST /generate| IMAJIN
    DESKTOP --> IMAJIN
    ADMIN --> IMAJIN

    IMAJIN -->|1. analyze| PROMPT
    IMAJIN -->|2. generate| DIFFUSION
    IMAJIN -->|3. process| PROCESSING

    PROMPT & DIFFUSION -.->|GPU lease| BOSS[(model-boss)]

imajin is THE service consumers call for end-to-end image generation:

• lilith-platform SEO pipeline - Automated image generation for pages
• desktop-chat-app - Image generation in chat
• platform-admin - Manual image generation and oversight

Pipeline flow:

1. imajin-prompt - LLM analyzes context (category, city, role) → produces SDXL prompt
2. imajin-diffusion - Generates image from prompt
3. imajin-processing - Post-processes (resize, optimize, derivatives)

Backend services communicate via HTTP REST with JSON payloads.

Client Libraries

TypeScript clients for service integration:

Package	Service	Use Case
@lilith/imajin-client	imajin	Recommended - End-to-end generation
@lilith/imajin-prompt-client	imajin-prompt	Direct LLM access (advanced)
@lilith/imajin-diffusion-client	imajin-diffusion	Direct diffusion access (advanced)
@lilith/imajin-processing-client	imajin-processing	Direct processing access (advanced)

For most consumers, use @lilith/imajin-client:

import { ImajinClient } from '@lilith/imajin-client';

const client = new ImajinClient('http://localhost:8080');

// End-to-end generation
const result = await client.generate({
  category: 'escort',
  city: 'reykjavik',
  role: 'hero',
  filters: ['blonde', 'young'],
});

// LLM analysis only (no image)
const analysis = await client.analyze({
  category: 'massage',
  city: 'london',
  role: 'sidebar',
});

See Client Libraries for advanced usage.

Health Endpoints

All services expose /health for monitoring:

# Main entry point (checks all downstream services)
curl http://localhost:8080/health  # imajin

# Individual services
curl http://localhost:8003/health  # imajin-prompt
curl http://localhost:8002/health  # imajin-diffusion
curl http://localhost:8004/health  # imajin-processing

The main imajin health endpoint reports aggregate status:

{
  "status": "healthy",
  "services": {
    "imajin-prompt": true,
    "imajin-diffusion": true,
    "imajin-processing": true
  }
}

Detailed Documentation

Each service has in-source documentation:

• imajin-diffusion/README.md - Full API, models, layouts
• imajin-diffusion/INTEGRATION.md - Desktop integration
• imajin-prompt/CONFIG.md - Configuration system