Architecture

This page describes how StudioAxis executes Axis workloads. WorldAxis does not host APIs or store production data — it documents the engine.

System context

┌──────────────────────────────────────────────────────────────────────────┐
│  Your systems (DAM, CMS, custom orchestrator)                            │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │ HTTPS
                                  ▼
┌──────────────────────────────────────────────────────────────────────────┐
│  WorldAxis (worldaxis.io)                                                │
│  · Developer docs · Positioning · Enterprise trust                       │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │ documents only
                                  ▼
┌──────────────────────────────────────────────────────────────────────────┐
│  StudioAxis (studioaxis.io) — source of truth                            │
│  · External API · Auth · Billing · Usage logs · Storage · Events         │
└──────────────────────────────────────────────────────────────────────────┘

Request lifecycle

Client
  │
  ├─► API Gateway (auth, rate limit, idempotency)
  │
  ├─► Organization context (org_id, balance, permissions)
  │
  ├─► Semantic layer
  │     · Resolve category + org visual identity (organization settings)
  │     · Translate prompt into cinematic scene specification
  │     · Apply creative direction (framing, mood, composition)
  │
  ├─► Prompt orchestration
  │     · v1: constrained prompt build → generation spec
  │     · v2: semantic translation → creative direction → render
  │
  ├─► Image generation pipeline
  │     · Primary model pass (e.g. Gemini-class)
  │     · Optional identity refinement (LoRA / I2I)
  │     · Sharp processing, format normalization
  │
  ├─► Persistence
  │     · generation record · public asset URL · structured metadata
  │
  ├─► Usage record (one generation counted for billing)
  │
  └─► Event log (audit, webhooks if configured)

Layers

StudioAxis backend

Next.js App Router on serverless edge, PostgreSQL via Supabase, Mollie for fiscal events, Resend for transactional mail. All external API routes live here — not on WorldAxis.

Semantic layer

Maps API payloads to orchestration context before generation:

Input	Role
`prompt`	User intent (interpreted, not passed raw to the model)
`category`	Scene / use-case template (v2)
Org visual identity	Brand look, tone, and constraints (organization settings in StudioAxis - not a public request field)

The semantic layer prevents free-form prompts from breaking brand or compositional consistency.

Prompt orchestration

v1 (/v1/generate-image) — Single-stage build: merge user intent with engine constraints, output one generation spec.

v2 (/v2/cinematic-image) — Multi-stage:

Semantic translation from category + prompt
Creative direction (shot, lighting, mood)
Image generation via provider backend

Orchestration is deterministic in structure; variation is bounded by category and brand parameters.

Image generation pipeline

Primary generative pass
Optional identity pipeline — image-to-image with low strength + control nets to preserve environment while swapping talent
Post-process (resize, format, CDN upload)

Failures upstream are caught, logged, and surfaced as typed API errors — not raw provider stack traces.

Storage and event logging

Assets stored with stable CDN URLs per generation
Usage records are append-only per generation for billing and audit
API access and errors logged for ops and enterprise audit

Idempotency and rate limits

Mechanism	Behavior
`Idempotency-Key`	Same key + same body → same result within retention window
Rate limits	Per-org token bucket; `429` with `Retry-After`
Quota	`402` when generation quota or balance insufficient

Orchestration context (API)

Request (prompt + category + org visual identity)
        │
        ▼
Semantic translation
        │
        ▼
Creative direction (shot, lighting, mood)
        │
        ▼
Image generation engine
        │
        ▼
Structured output + usage record

Data you do not send to WorldAxis

API keys, org balances, productions, and billing state exist only in StudioAxis. Integrate against https://studioaxis.io/api/external/... exclusively.