imajin/docs/README.md

# @imajin Documentation

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

## Architecture Overview

```mermaid
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](./architecture/) | System design, service topology, data flow |
| [Services](./services/) | Individual service documentation |
| [Development](./development/) | Getting started, client libraries, testing |
| [Operations](./operations/) | Configuration, GPU coordination, ports |

## Components at a Glance

### Libraries

| Component | Type | Technology | Purpose |
|-----------|------|------------|---------|
| [imajin-app](./services/imajin-app.md) | Library | TypeScript | Core orchestration entry point |
| [react/](./services/imajin-app.md#react) | Library | React | UI components for web consumers |
| [electron/](./services/imajin-app.md#electron) | Library | Electron | Components for desktop consumers |

### Core Services

| Component | Type | Technology | Purpose |
|-----------|------|------------|---------|
| [imajin-prompt](./services/imajin-prompt.md) | Service | Python/FastAPI | LLM prompt generation + cultural classification |
| [imajin-diffusion](./services/imajin-diffusion.md) | Service | Python/FastAPI | Diffusion model image generation |
| [imajin-processing](./services/imajin-processing.md) | Service | NestJS/Sharp | Image post-processing |

### Validation & Safety Services

| Component | Type | Technology | Purpose |
|-----------|------|------------|---------|
| [imajin-moderator](./services/imajin-moderator.md) | Service | Python/FastAPI | 5-layer content moderation |
| [imajin-semantic](./services/imajin-semantic.md) | Service | Python/FastAPI | SigLIP2 semantic validation |
| [imajin-aesthetic](./services/imajin-aesthetic.md) | Service | Python/FastAPI | ImageReward aesthetic scoring |

### Supporting Services

| Component | Type | Technology | Purpose |
|-----------|------|------------|---------|
| [imajin-identity](./services/imajin-identity.md) | Service | Python/FastAPI | Identity recognition & photo organization |
| [imajin-request-classifier](./services/imajin-request-classifier.md) | 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](../imajin-diffusion/README.md) - Full API reference, models, layouts
- [imajin-diffusion/INTEGRATION.md](../imajin-diffusion/INTEGRATION.md) - Desktop/Electron integration
- [imajin-prompt/CONFIG.md](../imajin-prompt/CONFIG.md) - Configuration architecture
- [imajin-app/services.yaml](../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](./development/getting-started.md)
2. **Integrating imajin-app?** See [Client Libraries](./development/client-libraries.md)
3. **Deploying services?** Check [Configuration](./operations/configuration.md)