imajin/docs/architecture/README.md

Architecture Overview

The @imajin platform provides AI-powered image generation through 9 backend services, 2 orchestrators, and a shared library layer consumed by multiple applications.

System Architecture

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

    subgraph "@imajin Library Layer"
        ELECTRON[@lilith/imajin-electron]
        REACTLIB[@lilith/imajin-react]
        CORE[@lilith/imajin-app]
    end

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

    subgraph "Core Service Layer"
        ASSIST[imajin-prompt :8003]
        GEN[imajin-diffusion :8002]
        PROC[imajin-processing :8004]
    end

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

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

    subgraph "Infrastructure Layer"
        REDIS[(Redis/GPUBoss)]
        GPU0[cuda:0]
        GPU1[cuda:1]
    end

    DESKTOP --> ELECTRON
    PLATFORM --> REACTLIB
    ERRPAGES & SKELETON --> CORE
    ELECTRON & REACTLIB --> CORE

    CORE --> PIPELINE & APPORCH

    PIPELINE --> ASSIST & GEN & PROC
    PIPELINE --> MOD & SEM & AES
    APPORCH --> REQCLASS & PROMPTGEN & GEN & PROC

    MOD --> SEM & IDENT

    ASSIST & GEN & SEM & AES --> REDIS
    REDIS --> GPU0 & GPU1

Consumer Applications

Application	Package	Purpose
desktop-chat-app	@lilith/imajin-electron	End-user image generation in chat
lilith-platform	@lilith/imajin-react	Features + platform-admin oversight
@ui/error-pages	@lilith/imajin-app	Error page images (404, 500)
@ui/skeleton-anime-girls	@lilith/imajin-app	Loading state images

Orchestration Layer

Two orchestrators for different deployment patterns:

imajin-pipeline (Self-Contained, 16 Stages)

Runs a complete pipeline including GPU work. Stages: validate → image loading → identity conditioning → image conditioning → generate → identity verification → anatomy fix → watermark removal → background removal → moderate → semantic validation → aesthetic validation → text overlay → watermark → quality → output.

Best for: All-in-one deployments with ControlNet, FLUX+PuLID, and multi-candidate generation.

imajin-app Orchestrator (Service Proxy)

Lightweight HTTP proxy that delegates to specialized services: request-classifier → prompt-generator → diffusion → processing. No GPU work locally.

Best for: Distributed deployments where services run on different machines.

Design Principles

Monorepo Per Service

Each backend service follows the same structure:

service-name/
├── service/     # Backend implementation (Python/NestJS)
├── types/       # TypeScript type definitions (@lilith/*-types)
├── client/      # HTTP client library (@lilith/*-client)
└── package.json # npm workspaces configuration

This pattern ensures:

• Type-safe API contracts between services
• Reusable client libraries for any TypeScript consumer
• Co-located tests and implementation

GPU Resource Coordination

Services that use GPU (imajin-prompt, imajin-diffusion, imajin-semantic, imajin-aesthetic) coordinate through GPUBoss:

1. Service requests VRAM lease from GPUBoss
2. GPUBoss checks Redis for available VRAM
3. Lease granted with device assignment (cuda:0, cuda:1)
4. Service loads model and performs inference
5. Lease released when complete

This prevents OOM errors when multiple services run concurrently.

Layered Safety

Content safety is not a single check — it's a layered pipeline:

1. Moderation (imajin-moderator) — PDQ hash matching, NSFW detection, age estimation, prohibited content detection, identity verification
2. Semantic validation (imajin-semantic) — SigLIP2 verifies generated images match requested filters
3. Aesthetic scoring (imajin-aesthetic) — ImageReward ensures images meet quality thresholds

Configuration Layering

Services use a two-layer configuration:

1. config.defaults.yaml - Version-controlled defaults
2. config.yaml - Deployment-specific overrides (gitignored)

See Configuration for details.

Architecture Documents

Document	Description
Positioning	What @imajin is (and isn't) relative to ComfyUI/A1111
Feature Roadmap	Adoptable features from the ecosystem
Service Topology	Port assignments, dependencies, startup order
Data Flow	Request lifecycle, sequence diagrams
Technology Stack	Languages, frameworks, build tools