imajin/docs

@imajin Documentation

AI-powered image generation platform with diffusion models, LLM prompt engineering, content moderation, semantic validation, and aesthetic scoring.

Architecture Overview

graph TB
    subgraph "Consumer Applications"
        DESKTOP[desktop-chat-app]
        PLATFORM[lilith-platform]
        ERRPAGES[@ui/error-pages]
        SKELETON[@ui/skeleton-anime-girls]
    end

    subgraph "@imajin Libraries"
        ELECTRON[electron/<br/>@lilith/imajin-electron]
        REACTLIB[react/<br/>@lilith/imajin-react]
        CORE[imajin-app/<br/>@lilith/imajin-app]
    end

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

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

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

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

    subgraph "Infrastructure"
        REDIS[(Redis/GPUBoss)]
        GPU[GPU/CUDA]
    end

    DESKTOP --> ELECTRON
    PLATFORM --> REACTLIB
    ERRPAGES & SKELETON --> CORE
    ELECTRON & REACTLIB --> CORE
    CORE --> PIPELINE & APP
    PIPELINE --> PROMPT & GEN & PROC
    PIPELINE --> MOD & SEM & AES
    APP --> REQCLASS & PROMPTGEN & GEN & PROC
    MOD --> SEM & IDENT
    PROMPT & GEN & SEM & AES --> REDIS --> GPU

Key consumers:

• desktop-chat-app - End-user image generation in chat conversations
• lilith-platform - Image generation features + platform-admin for orchestration oversight
• @packages/@ui - Shared UI packages (error-pages, skeleton-anime-girls)

Quick Navigation

Section	Description
Architecture	System design, service topology, data flow
Services	Individual service documentation
Development	Getting started, client libraries, testing
Operations	Configuration, GPU coordination, ports

Components at a Glance

Libraries

Component	Type	Technology	Purpose
imajin-app	Library	TypeScript	Core orchestration entry point
react/	Library	React	UI components for web consumers
electron/	Library	Electron	Components for desktop consumers

Core Services

Component	Type	Technology	Purpose
imajin-prompt	Service	Python/FastAPI	LLM prompt generation + cultural classification
imajin-diffusion	Service	Python/FastAPI	Diffusion model image generation
imajin-processing	Service	NestJS/Sharp	Image post-processing

Validation & Safety Services

Component	Type	Technology	Purpose
imajin-moderator	Service	Python/FastAPI	5-layer content moderation
imajin-semantic	Service	Python/FastAPI	SigLIP2 semantic validation
imajin-aesthetic	Service	Python/FastAPI	ImageReward aesthetic scoring

Supporting Services

Component	Type	Technology	Purpose
imajin-identity	Service	Python/FastAPI	Identity recognition & photo organization
imajin-request-classifier	Service	Python/FastAPI	Cultural context classification (thin client)
imajin-prompt-generator	Service	Python/FastAPI	Lightweight prompt generation (Stage 2 only)

Orchestrators

Component	Type	Technology	Purpose
imajin-pipeline	Orchestrator	Python/FastAPI	16-stage self-contained pipeline
imajin-app (orchestrator)	Orchestrator	Python/FastAPI	Service proxy with batch support

Existing Documentation

Detailed documentation exists in each service directory:

• imajin-diffusion/README.md - Full API reference, models, layouts
• imajin-diffusion/INTEGRATION.md - Desktop/Electron integration
• imajin-prompt/CONFIG.md - Configuration architecture
• imajin-app/services.yaml - Port definitions, environments

Repository Structure

@imajin/
├── packages/
│   ├── imajin-app/            # Core orchestration entry point (@lilith/imajin-app)
│   ├── imajin-react/          # React components (@lilith/imajin-react)
│   ├── imajin-electron/       # Electron components (@lilith/imajin-electron)
│   ├── imajin-client/         # Unified HTTP client (@lilith/imajin-client)
│   ├── imajin-config/         # Shared configuration (@lilith/imajin-config)
│   └── imajin-moderator-client/  # Moderator client (@lilith/imajin-moderator-client)
│
├── services/
│   ├── imajin-diffusion/      # SDXL image generation (service + types + client)
│   ├── imajin-prompt/         # LLM prompt generation (service + types + client)
│   ├── imajin-processing/     # Post-processing (service + types + client)
│   ├── imajin-moderator/      # Content moderation (service + types + client)
│   ├── imajin-semantic/       # Semantic validation (service + types + client)
│   ├── imajin-aesthetic/      # Aesthetic scoring (service + types + client)
│   ├── imajin-identity/       # Identity recognition (service)
│   ├── imajin-request-classifier/  # Cultural classification (service)
│   └── imajin-prompt-generator/    # Lightweight prompt generation (service)
│
├── orchestrators/
│   ├── imajin-pipeline/       # 16-stage self-contained pipeline
│   └── imajin-app/            # Service proxy orchestrator
│
├── tests/                     # Integration tests
├── scripts/                   # Build & dev scripts
└── docs/                      # This documentation

Consumer Integration

imajin-app is a library, not a standalone app. Consumers:

Consumer	Uses imajin-app for
desktop-chat-app	Image generation in chat conversations
lilith-platform	Image generation features (SEO pages, content, etc.)
lilith-platform (platform-admin)	Pipeline monitoring & orchestration management
@packages/@ui/error-pages	Generated error page images
@packages/@ui/skeleton-anime-girls	Skeleton loading state images

Getting Started

1. New to the project? Start with Getting Started
2. Integrating imajin-app? See Client Libraries
3. Deploying services? Check Configuration