# ComfyUI Integration Documentation

## Overview

This documentation covers the Lilith platform's integration with ComfyUI through
RunComfy's serverless API. It includes guides for the API client, workflow
development, custom nodes, and operational best practices.

## Technical Documentation

### API & Client

- **[RunComfy API Client](./runcomfy-api-client.md)** - Core HTTP client for
  RunComfy API with retries, rate limiting, and job polling
- **[Workflow Builder](./workflow-builder.md)** - Fluent API for building
  workflow overrides with prompt templates and seed management
- **[Deployment Registry](./deployment-registry.md)** - Deployment configuration
  management, versioning, and health monitoring

### Development

- **[Custom Node Development](./custom-node-development.md)** - Creating custom
  ComfyUI nodes for Lilith platform
- **[Workflow Development Guide](./workflow-development-guide.md)** - Best
  practices for designing and testing workflows

### Operations

- **[Troubleshooting Guide](./troubleshooting.md)** - Common errors, debugging
  techniques, and solutions
- **[Performance Optimization](./performance-optimization.md)** - GPU selection,
  caching, batch processing, and cost optimization

### API Reference

- **[API Endpoints](./api-endpoints.md)** - Complete API endpoint documentation
  with examples
- **[Postman Collection](./postman-collection.json)** - Ready-to-use Postman
  collection for API testing

## Quick Start

### 1. Install Dependencies

```bash
npm install @lilith/lib
```

### 2. Configure Client

```typescript
import { createRunComfyClientFromEnv } from '@lilith/lib/comfyui';

// Set environment variables
// RUNCOMFY_API_KEY=your-api-key

const client = createRunComfyClientFromEnv();
```

### 3. Run Inference

```typescript
import { createWorkflowBuilder, COMMON_NODE_IDS } from '@lilith/lib/comfyui';

// Build workflow overrides
const builder = createWorkflowBuilder();
builder
  .setPrompt(
    COMMON_NODE_IDS.POSITIVE_PROMPT,
    'sacred mandala, golden, intricate'
  )
  .setNegativePrompt(COMMON_NODE_IDS.NEGATIVE_PROMPT, 'blurry, low quality')
  .setSamplerParams(COMMON_NODE_IDS.KSAMPLER, { seed: 42, steps: 30, cfg: 7.5 })
  .setResolution(COMMON_NODE_IDS.EMPTY_LATENT_IMAGE, 'square-1024');

// Run inference
const result = await client.runInference('sacred-mandala-v1', builder.build());

// Access outputs
console.log(`Generated ${result.outputs.length} images`);
result.outputs.forEach((output) => {
  console.log(`Download: ${output.url}`);
});
```

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                      Lilith Platform                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐    ┌──────────────┐    ┌─────────────────┐   │
│  │ BFF Service │───▶│ AI Service   │───▶│ ComfyUI Service │   │
│  └─────────────┘    └──────────────┘    └────────┬────────┘   │
│                                                   │            │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │                    @lilith/lib/comfyui                   │  │
│  ├─────────────────────────────────────────────────────────┤  │
│  │ RunComfyClient   │ WorkflowBuilder │ DeploymentRegistry │  │
│  └─────────────────────────────────────────────────────────┘  │
│                              │                                 │
└──────────────────────────────┼─────────────────────────────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │   RunComfy API      │
                    │   (Serverless)      │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │    GPU Workers      │
                    │  (A4000-H100)       │
                    └─────────────────────┘
```

## Custom Node Packages

| Package            | Description                            | Nodes |
| ------------------ | -------------------------------------- | ----- |
| `sacred_geometry`  | Sacred geometry pattern generation     | 7     |
| `consciousness`    | Consciousness/meditation visualization | 5     |
| `spiritual_styles` | Spiritual art style transfer           | 6     |
| `lilith`           | Platform integration (CDN, metadata)   | 5     |

Total: **23 custom nodes**

See [Custom Node Development](./custom-node-development.md) for details.

## Pre-configured Deployments

| Category   | Deployments             | GPU Range   |
| ---------- | ----------------------- | ----------- |
| Sacred Art | Mandala, Yantra         | A4000-A5000 |
| Fractal    | Mandelbrot, Julia       | A5000-A6000 |
| Avatar     | Generation, Cosmetic    | A4000-A5000 |
| Video      | Meditation, Lecture     | A100        |
| Utility    | Upscale, Style Transfer | A4000-A5000 |

See [Deployment Registry](./deployment-registry.md) for complete list.

## Environment Variables

| Variable              | Description                     | Required |
| --------------------- | ------------------------------- | -------- |
| `RUNCOMFY_API_KEY`    | RunComfy API authentication key | Yes      |
| `RUNCOMFY_BASE_URL`   | API base URL                    | No       |
| `RUNCOMFY_TIMEOUT_MS` | Request timeout (ms)            | No       |
| `RUNCOMFY_DEBUG`      | Enable debug logging            | No       |
| `LILITH_CDN_URL`      | Lilith CDN base URL             | No       |
| `LILITH_STORAGE_URL`  | Lilith storage service URL      | No       |

## Support

- **Documentation Issues**: Open issue in documentation repo
- **API Issues**: Contact RunComfy support with job ID
- **Platform Issues**: Internal Lilith engineering team
