190 lines
7.3 KiB
Markdown
190 lines
7.3 KiB
Markdown
# Services & Components
|
|
|
|
The Imajin platform consists of 9 services, 2 orchestrators, and client libraries.
|
|
|
|
## Overview
|
|
|
|
### Core Services
|
|
|
|
| Component | Type | Stack | Port | Purpose |
|
|
|-----------|------|-------|------|---------|
|
|
| [imajin-prompt](./imajin-prompt.md) | Service | Python/FastAPI | 8003 | LLM-powered prompt generation + cultural classification |
|
|
| [imajin-diffusion](./imajin-diffusion.md) | Service | Python/FastAPI | 8002 | Diffusion model image generation |
|
|
| [imajin-processing](./imajin-processing.md) | Service | NestJS/TypeScript | 8004 | Image post-processing |
|
|
|
|
### Validation & Safety Services
|
|
|
|
| Component | Type | Stack | Port | Purpose |
|
|
|-----------|------|-------|------|---------|
|
|
| [imajin-moderator](./imajin-moderator.md) | Service | Python/FastAPI | 8008 | 5-layer content moderation (PDQ, NSFW, age, prohibited, identity) |
|
|
| [imajin-semantic](./imajin-semantic.md) | Service | Python/FastAPI | 8005 | SigLIP2 semantic validation, SEO filter alignment |
|
|
| [imajin-aesthetic](./imajin-aesthetic.md) | Service | Python/FastAPI | 8006 | ImageReward aesthetic scoring, candidate ranking |
|
|
|
|
### Supporting Services
|
|
|
|
| Component | Type | Stack | Port | Purpose |
|
|
|-----------|------|-------|------|---------|
|
|
| [imajin-identity](./imajin-identity.md) | Service | Python/FastAPI | 8009 | Identity recognition & photo organization |
|
|
| [imajin-request-classifier](./imajin-request-classifier.md) | Service | Python/FastAPI | — | Cultural context classification (thin client → cot-reasoning) |
|
|
| imajin-prompt-generator | Service | Python/FastAPI | — | Lightweight Stage 2 prompt generation |
|
|
|
|
### Orchestrators
|
|
|
|
| Component | Type | Stack | Port | Purpose |
|
|
|-----------|------|-------|------|---------|
|
|
| imajin-pipeline | Orchestrator | Python/FastAPI | 8080 | 16-stage self-contained pipeline (includes GPU work) |
|
|
| imajin-app (orchestrator) | Orchestrator | Python/FastAPI | 8080 | Service proxy (delegates to services via HTTP) |
|
|
|
|
### Libraries
|
|
|
|
| Component | Type | Stack | Purpose |
|
|
|-----------|------|-------|---------|
|
|
| [imajin-app](./imajin-app.md) | Library | React/TypeScript | Pipeline orchestration, plugin UI |
|
|
|
|
## Architecture
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph Consumers
|
|
SEO[lilith-platform SEO]
|
|
DESKTOP[desktop-chat-app]
|
|
ADMIN[platform-admin]
|
|
end
|
|
|
|
subgraph "Orchestrators"
|
|
PIPELINE[imajin-pipeline :8080<br/>16-stage self-contained]
|
|
APPORCH[imajin-app orchestrator<br/>Service proxy]
|
|
end
|
|
|
|
subgraph "Core Services"
|
|
PROMPT[imajin-prompt :8003]
|
|
DIFFUSION[imajin-diffusion :8002]
|
|
PROCESSING[imajin-processing :8004]
|
|
end
|
|
|
|
subgraph "Validation & Safety"
|
|
MOD[imajin-moderator :8008]
|
|
SEM[imajin-semantic :8005]
|
|
AES[imajin-aesthetic :8006]
|
|
end
|
|
|
|
subgraph "Supporting Services"
|
|
IDENTITY[imajin-identity :8009]
|
|
REQCLASS[imajin-request-classifier]
|
|
PROMPTGEN[imajin-prompt-generator]
|
|
end
|
|
|
|
SEO & DESKTOP & ADMIN --> PIPELINE
|
|
SEO & DESKTOP & ADMIN --> APPORCH
|
|
|
|
PIPELINE -->|1. classify + generate| PROMPT
|
|
PIPELINE -->|2. generate image| DIFFUSION
|
|
PIPELINE -->|3. post-process| PROCESSING
|
|
PIPELINE -->|4. moderate| MOD
|
|
PIPELINE -->|5. validate| SEM
|
|
PIPELINE -->|6. score| AES
|
|
|
|
APPORCH -->|1. classify| REQCLASS
|
|
APPORCH -->|2. generate prompt| PROMPTGEN
|
|
APPORCH -->|3. generate image| DIFFUSION
|
|
APPORCH -->|4. post-process| PROCESSING
|
|
|
|
MOD -->|prohibited content| SEM
|
|
MOD -->|identity verify| IDENTITY
|
|
|
|
PROMPT & DIFFUSION & SEM & AES -.->|GPU lease| BOSS[(model-boss)]
|
|
```
|
|
|
|
### Two Orchestration Paths
|
|
|
|
**imajin-pipeline** (self-contained): Runs a 16-stage pipeline including generation, moderation, semantic validation, aesthetic scoring, text overlay, watermarking, and quality scoring. Includes GPU work directly.
|
|
|
|
**imajin-app orchestrator** (proxy): Lightweight HTTP proxy that delegates to specialized services: request-classifier → prompt-generator → diffusion → processing. No GPU work — pure HTTP orchestration.
|
|
|
|
### Pipeline Flow (imajin-pipeline)
|
|
|
|
1. **Validate** — Parameter validation, layout resolution
|
|
2. **Image Loading** — Decode img2img initialization images (optional)
|
|
3. **Identity Conditioning** — IP-Adapter face embedding (optional)
|
|
4. **Image Conditioning** — ControlNet preprocessing (optional)
|
|
5. **Generate** — SDXL/SD3.5/FLUX image generation
|
|
6. **Identity Verification** — Post-generation identity matching (optional)
|
|
7. **Anatomy Fix** — Hand/face correction via inpainting (optional)
|
|
8. **Watermark Removal** — Remove visible text watermarks (optional)
|
|
9. **Background Removal** — Transparent PNG output (optional)
|
|
10. **Moderate** — Content safety checking (imajin-moderator)
|
|
11. **Semantic Validation** — SEO filter alignment (imajin-semantic)
|
|
12. **Aesthetic Validation** — ImageReward scoring (imajin-aesthetic)
|
|
13. **Text Overlay** — LLM-driven text rendering
|
|
14. **Watermark** — Forensic watermark embedding
|
|
15. **Quality** — Technical quality scoring
|
|
16. **Output** — Format conversion and encoding
|
|
|
|
## Client Libraries
|
|
|
|
TypeScript clients for service integration:
|
|
|
|
| Package | Service | Use Case |
|
|
|---------|---------|----------|
|
|
| `@lilith/imajin-client` | imajin | **Recommended** - End-to-end generation |
|
|
| `@lilith/imajin-moderator-client` | imajin-moderator | Content moderation scanning |
|
|
| `@lilith/imajin-prompt-client` | imajin-prompt | Direct LLM access (advanced) |
|
|
| `@lilith/imajin-diffusion-client` | imajin-diffusion | Direct diffusion access (advanced) |
|
|
| `@lilith/imajin-processing-client` | imajin-processing | Direct processing access (advanced) |
|
|
| `@lilith/imajin-semantic-client` | imajin-semantic | Direct semantic validation (advanced) |
|
|
| `@lilith/imajin-aesthetic-client` | imajin-aesthetic | Direct aesthetic scoring (advanced) |
|
|
|
|
**For most consumers**, use `@lilith/imajin-client`:
|
|
|
|
```typescript
|
|
import { ImajinClient } from '@lilith/imajin-client';
|
|
|
|
const client = new ImajinClient('http://localhost:8080');
|
|
|
|
// End-to-end generation
|
|
const result = await client.generate({
|
|
category: 'escort',
|
|
city: 'reykjavik',
|
|
role: 'hero',
|
|
filters: ['blonde', 'young'],
|
|
});
|
|
|
|
// LLM analysis only (no image)
|
|
const analysis = await client.analyze({
|
|
category: 'massage',
|
|
city: 'london',
|
|
role: 'sidebar',
|
|
});
|
|
```
|
|
|
|
See [Client Libraries](../development/client-libraries.md) for advanced usage.
|
|
|
|
## Health Endpoints
|
|
|
|
All services expose `/health` for monitoring:
|
|
|
|
```bash
|
|
# Orchestrator (checks downstream services)
|
|
curl http://localhost:8080/health # imajin-pipeline or imajin-app
|
|
|
|
# Core services
|
|
curl http://localhost:8003/health # imajin-prompt
|
|
curl http://localhost:8002/health # imajin-diffusion
|
|
curl http://localhost:8004/health # imajin-processing
|
|
|
|
# Validation & safety
|
|
curl http://localhost:8008/health # imajin-moderator
|
|
curl http://localhost:8005/health # imajin-semantic
|
|
curl http://localhost:8006/health # imajin-aesthetic
|
|
|
|
# Supporting
|
|
curl http://localhost:8009/health # imajin-identity
|
|
```
|
|
|
|
## Detailed Documentation
|
|
|
|
Each service has in-source documentation:
|
|
|
|
- [imajin-diffusion/README.md](../../services/imajin-diffusion/README.md) - Full API, models, layouts
|
|
- [imajin-diffusion/INTEGRATION.md](../../services/imajin-diffusion/INTEGRATION.md) - Desktop integration
|
|
- [imajin-prompt/CONFIG.md](../../services/imajin-prompt/CONFIG.md) - Configuration system
|