imajin/docs/architecture

Architecture Overview

The @imajin platform provides AI-powered image generation through backend services and a shared orchestration library 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 "Service Layer"
        ASSIST[imajin-prompt :8003]
        GEN[imajin-diffusion :8002]
        PROC[imajin-processing :8004]
    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 --> ASSIST & GEN & PROC
    ASSIST & GEN --> 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

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) 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.

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
Service Topology	Port assignments, dependencies, startup order
Data Flow	Request lifecycle, sequence diagrams
Technology Stack	Languages, frameworks, build tools