imajin/docs/architecture/technology-stack.md

Technology Stack

Language Boundaries

graph TD
    subgraph "TypeScript"
        APP[imagen-app]
        PROC[image-processing]
        CLIENTS[Client Libraries]
        TYPES[Type Definitions]
    end

    subgraph "Python"
        GEN[image-generation]
        ASSIST[imagegen-assistant]
        ML[ML Libraries]
    end

    CLIENTS --> TYPES
    APP --> CLIENTS
    GEN --> ML
    ASSIST --> ML

Python is used for ML-heavy services (diffusion models, LLM) where PyTorch ecosystem is required.

TypeScript is used for web services and client libraries for type safety.

Service Stacks

imagen-app (TypeScript)

Layer	Technology
UI	React 18, styled-components
State	TanStack Query
Build	Vite, tsup
Testing	Vitest, React Testing Library
Package	npm workspaces

imagegen-assistant (Python)

Layer	Technology
API	FastAPI, uvicorn
Validation	Pydantic
LLM	DeepSeek R1 70B, llama-cpp-python
GPU	GPUBoss, Redis
Build	hatchling

image-generation (Python)

Layer	Technology
API	FastAPI, uvicorn
Validation	Pydantic
ML	diffusers, torch, transformers
Pipeline	lilith-image-pipeline (7-stage)
GPU	GPUBoss, Redis, CUDA
Build	hatchling

image-processing (TypeScript)

Layer	Technology
Framework	NestJS
Image	Sharp
Validation	class-validator
Build	nest-cli

Monorepo Pattern

Each service follows the same structure:

graph TD
    subgraph "Service Monorepo"
        SVC[service/<br/>Python FastAPI<br/>or NestJS]
        TYPES[types/<br/>@lilith/*-types<br/>Zod schemas]
        CLIENT[client/<br/>@lilith/*-client<br/>HTTP client]

        CLIENT --> TYPES
    end

Package Naming

Workspace	Package Name Pattern
types	@lilith/{service}-types
client	@lilith/{service}-client
core	@lilith/{service}-core
react	@lilith/{service}-react

Type Safety Strategy

graph LR
    PY[Python Pydantic] -->|Manual sync| ZOD[TypeScript Zod]
    ZOD --> CLIENT[Client Library]
    CLIENT --> APP[Consumer App]

1. Python services define Pydantic models
2. TypeScript types mirror Pydantic models using Zod
3. Client libraries use Zod for runtime validation
4. Consumer apps get compile-time + runtime type safety

Build Tools

Context	Tool	Purpose
TypeScript bundling	tsup	Fast ESM/CJS builds
TypeScript monorepo	npm workspaces	Package management
Python packaging	hatchling	PEP 517 builds
Python dependencies	pip + venv	Virtual environments
Docker	Dockerfile	GPU deployment

ML Stack

Diffusion Model Generation

Component	Library
Model loading	diffusers
GPU acceleration	torch (CUDA)
Text encoding	transformers
Memory optimization	accelerate
Pipeline orchestration	lilith-image-pipeline

LLM Inference

Component	Library
Model loading	llama-cpp-python
GGUF models	DeepSeek R1 70B
Alternative	Ollama (optional)

Infrastructure

Component	Technology
GPU coordination	GPUBoss (custom)
State sharing	Redis
Desktop integration	Electron IPC
Container runtime	Docker + NVIDIA runtime