imajin/docs/services

Services & Components

The Imajin platform consists of 9 services, 2 orchestrators, and client libraries.

Overview

Core Services

Component	Type	Stack	Port	Purpose
imajin-prompt	Service	Python/FastAPI	8003	LLM-powered prompt generation + cultural classification
imajin-diffusion	Service	Python/FastAPI	8002	Diffusion model image generation
imajin-processing	Service	NestJS/TypeScript	8004	Image post-processing

Validation & Safety Services

Component	Type	Stack	Port	Purpose
imajin-moderator	Service	Python/FastAPI	8008	5-layer content moderation (PDQ, NSFW, age, prohibited, identity)
imajin-semantic	Service	Python/FastAPI	8005	SigLIP2 semantic validation, SEO filter alignment
imajin-aesthetic	Service	Python/FastAPI	8006	ImageReward aesthetic scoring, candidate ranking

Supporting Services

Component	Type	Stack	Port	Purpose
imajin-identity	Service	Python/FastAPI	8009	Identity recognition & photo organization
imajin-request-classifier	Service	Python/FastAPI	—	Cultural context classification (thin client → cot-reasoning)
imajin-prompt-generator	Service	Python/FastAPI	—	Lightweight Stage 2 prompt generation

Orchestrators

Component	Type	Stack	Port	Purpose
imajin-pipeline	Orchestrator	Python/FastAPI	8080	16-stage self-contained pipeline (includes GPU work)
imajin-app (orchestrator)	Orchestrator	Python/FastAPI	8080	Service proxy (delegates to services via HTTP)

Libraries

Component	Type	Stack	Purpose
imajin-app	Library	React/TypeScript	Pipeline orchestration, plugin UI

Architecture

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

    subgraph "Orchestrators"
        PIPELINE[imajin-pipeline :8080<br/>16-stage self-contained]
        APPORCH[imajin-app orchestrator<br/>Service proxy]
    end

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

    subgraph "Validation & Safety"
        MOD[imajin-moderator :8008]
        SEM[imajin-semantic :8005]
        AES[imajin-aesthetic :8006]
    end

    subgraph "Supporting Services"
        IDENTITY[imajin-identity :8009]
        REQCLASS[imajin-request-classifier]
        PROMPTGEN[imajin-prompt-generator]
    end

    SEO & DESKTOP & ADMIN --> PIPELINE
    SEO & DESKTOP & ADMIN --> APPORCH

    PIPELINE -->|1. classify + generate| PROMPT
    PIPELINE -->|2. generate image| DIFFUSION
    PIPELINE -->|3. post-process| PROCESSING
    PIPELINE -->|4. moderate| MOD
    PIPELINE -->|5. validate| SEM
    PIPELINE -->|6. score| AES

    APPORCH -->|1. classify| REQCLASS
    APPORCH -->|2. generate prompt| PROMPTGEN
    APPORCH -->|3. generate image| DIFFUSION
    APPORCH -->|4. post-process| PROCESSING

    MOD -->|prohibited content| SEM
    MOD -->|identity verify| IDENTITY

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

Two Orchestration Paths

imajin-pipeline (self-contained): Runs a 16-stage pipeline including generation, moderation, semantic validation, aesthetic scoring, text overlay, watermarking, and quality scoring. Includes GPU work directly.

imajin-app orchestrator (proxy): Lightweight HTTP proxy that delegates to specialized services: request-classifier → prompt-generator → diffusion → processing. No GPU work — pure HTTP orchestration.

Pipeline Flow (imajin-pipeline)

1. Validate — Parameter validation, layout resolution
2. Image Loading — Decode img2img initialization images (optional)
3. Identity Conditioning — IP-Adapter face embedding (optional)
4. Image Conditioning — ControlNet preprocessing (optional)
5. Generate — SDXL/SD3.5/FLUX image generation
6. Identity Verification — Post-generation identity matching (optional)
7. Anatomy Fix — Hand/face correction via inpainting (optional)
8. Watermark Removal — Remove visible text watermarks (optional)
9. Background Removal — Transparent PNG output (optional)
10. Moderate — Content safety checking (imajin-moderator)
11. Semantic Validation — SEO filter alignment (imajin-semantic)
12. Aesthetic Validation — ImageReward scoring (imajin-aesthetic)
13. Text Overlay — LLM-driven text rendering
14. Watermark — Forensic watermark embedding
15. Quality — Technical quality scoring
16. Output — Format conversion and encoding

Client Libraries

TypeScript clients for service integration:

Package	Service	Use Case
@lilith/imajin-client	imajin	Recommended - End-to-end generation
@lilith/imajin-moderator-client	imajin-moderator	Content moderation scanning
@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)
@lilith/imajin-semantic-client	imajin-semantic	Direct semantic validation (advanced)
@lilith/imajin-aesthetic-client	imajin-aesthetic	Direct aesthetic scoring (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:

# Orchestrator (checks downstream services)
curl http://localhost:8080/health  # imajin-pipeline or imajin-app

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

# Validation & safety
curl http://localhost:8008/health  # imajin-moderator
curl http://localhost:8005/health  # imajin-semantic
curl http://localhost:8006/health  # imajin-aesthetic

# Supporting
curl http://localhost:8009/health  # imajin-identity

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