# Technology Stack

## Language Boundaries

```mermaid
graph TD
    subgraph "TypeScript"
        APP[imajin-app]
        PROC[imajin-processing]
        CLIENTS[Client Libraries]
        TYPES[Type Definitions]
    end

    subgraph "Python"
        GEN[imajin-diffusion]
        ASSIST[imajin-prompt]
        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

### imajin-app (TypeScript)

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

### imajin-prompt (Python)

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

### imajin-diffusion (Python)

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

### imajin-processing (TypeScript)

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

## Monorepo Pattern

Each service follows the same structure:

```mermaid
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

```mermaid
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-imajin-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 |