Zoltraak Gateway -- Domain Model

Scope

This document defines all DTOs that cross the boundary between Zoltraak Gateway and its external clients. These are the shapes clients send to the gateway and receive back from it. They are not used internally between services and they do not map to external provider APIs. All DTOs are wrapped in GatewayResponse when returned to clients.

Fantasy Mode DTOs

classDiagram
    class FantasyRequest {
        String imageBase64
        String prompt
        boolean includeImageGeneration
    }

    class FantasyResponse {
        String story
        String imageBase64
        FantasyStage stage
        List~String~ warnings
    }

    FantasyResponse --> FantasyStage

FantasyRequest


Purpose	Inbound payload for POST /api/v1/fantasy/generate. Carries the image to analyse, an optional creative prompt to guide the story, and whether the client wants an illustration generated alongside the story.
Key Constraints	imageBase64 is required. prompt is optional. If absent the vision model uses a default system prompt. includeImageGeneration defaults to false if not provided. Maximum image size is enforced at the controller layer before the DTO is passed to the orchestrator.

FantasyResponse


Purpose	Outbound payload for POST /api/v1/fantasy/generate. Returns the generated story, an optional illustration, the furthest pipeline stage reached, and any non-fatal warnings.
Key Constraints	story is always present when stage is STORY_COMPLETE, IMAGE_COMPLETE. imageBase64 is null when includeImageGeneration was false or image generation failed gracefully. warnings is an empty list on full success. A response with STORY_COMPLETE stage and non-empty warnings is a valid partial success, not an error.

Chat Proxy DTOs

These DTOs define the Ollama-compatible surface that OpenWebUI and other Ollama clients send to the gateway. They mirror the Ollama API contract exactly so OpenWebUI requires no modification.

classDiagram
    class OllamaProxyChatRequest {
        String model
        List~ChatMessage~ messages
        boolean stream
    }

    class OllamaProxyGenerateRequest {
        String model
        String prompt
        List~String~ images
        boolean stream
    }

    class ChatMessage {
        String role
        String content
    }

    class OllamaProxyTagsResponse {
        List~OllamaModelEntry~ models
    }

    class OllamaModelEntry {
        String name
        String model
        String modifiedAt
        Long size
    }

    OllamaProxyChatRequest --> ChatMessage
    OllamaProxyTagsResponse --> OllamaModelEntry

OllamaProxyChatRequest


Purpose	Inbound payload received from OpenWebUI on the Ollama-compatible chat endpoint POST /api/v1/chat. Mirrors the Ollama /api/chat contract so OpenWebUI works without modification.
Key Constraints	role in ChatMessage is one of: system, user, assistant. model must match a model loaded on the GPU pod Ollama instance. stream is passed through to the upstream Ollama instance unchanged.

OllamaProxyGenerateRequest


Purpose	Inbound payload for the Ollama-compatible generate endpoint. Some OpenWebUI versions use /api/generate rather than /api/chat. Both are supported.
Key Constraints	images is only populated for multimodal requests. For standard text generation it is an empty list.

ChatMessage


Purpose	Represents a single message in a conversation history. Used in OllamaProxyChatRequest.
Key Constraints	role is a string not an enum because the Ollama protocol uses raw string values and additional roles may be introduced by Ollama without a gateway change.

OllamaProxyTagsResponse


Purpose	Response shape for GET /api/tags. Returned to OpenWebUI so it can populate its model selector. Mirrors the Ollama /api/tags contract.
Key Constraints	When the pod is not READY the gateway returns an empty models list rather than triggering a pod start for a metadata request.