Scope

This document defines all Enums and the universal response envelope used across the entire system. Every other domain model document depends on the types defined here. These must be finalized before any other domain model classes are written.

classDiagram
    class PodStatus {
        <<enumeration>>
        STOPPED
        STARTING
        WARMING
        READY
        STOPPING
    }

    class GpuProvider {
        <<enumeration>>
        RUNPOD
        VASTAI
    }

    class FantasyStage {
        <<enumeration>>
        STORY_COMPLETE
        IMAGE_COMPLETE
        FAILED
    }

    class GatewayErrorCode {
        <<enumeration>>
        INVALID_TOKEN
        TOKEN_EXPIRED
        POD_START_FAILED
        WARMUP_TIMEOUT
        QUEUE_TIMEOUT
        STORY_FAILED
        IMAGE_GEN_FAILED
        PROVIDER_UNAVAILABLE
        INTENT_UNRESOLVED
        INTERNAL_ERROR
    }

    class BotIntent {
        <<enumeration>>
        POD_STATUS
        POD_START
        POD_STOP
        COST_SUMMARY
        FANTASY_GENERATE
        HEALTH_CHECK
        UNRECOGNISED
    }

    class ModelType {
        <<enumeration>>
        VISION
        CHAT
        CODE
        INTENT
    }

Enums

Class Constraints

Class	Purpose	Key Constraints
`PodStatus`	Represents every state a GPU pod can be in during its lifecycle. Used by the GPU Lifecycle Manager to gate request forwarding, drive background process activation, and report status to clients and the bot.	Only `READY` permits request forwarding to Ollama or ComfyUI. Transitions are strictly ordered per the state machine in the architecture document. No transition skips a state. `STOPPING` must not accept new requests.
`GpuProvider`	Identifies which cloud provider is active. Drives adapter selection in the Provider Abstraction Layer for all `start`, `stop`, `status`, and connection detail operations.	Exactly one provider is active at a time per gateway configuration. Cannot change while a pod is running. Selection is driven by the `zoltraak.provider` configuration property.
`FantasyStage`	Tracks how far through the Fantasy Mode pipeline a request progressed. Always included in `FantasyResponse` so the client knows whether the result is complete or partial.	`IMAGE_COMPLETE` is only reachable when the client set `includeImageGeneration` to true. `STORY_COMPLETE` with no image is a valid successful outcome when image generation was not requested. `FAILED` means the pipeline could not produce a story at all.
`GatewayErrorCode`	Machine-readable error codes included in every error response envelope. Allows clients to handle specific failure scenarios programmatically without parsing message strings.	Codes are uppercase snake case strings. New codes must be added here before being used in any error response. `INTERNAL_ERROR` is the fallback for unexpected failures.
`BotIntent`	Represents the set of actions the Telegram bot can resolve from natural language input. Produced by the intent classifier and consumed by the Telegram Bot Service to route to the correct internal service.	`UNRECOGNISED` is returned when the local Ollama classifier cannot map the input to a known intent. The bot service must handle `UNRECOGNISED` gracefully with a helpful reply. New intents require a corresponding handler in the bot service before being added here.
`ModelType`	Categorises the purpose of an Ollama model. Used in configuration and model selection logic to map request types to the correct loaded model.	`INTENT` is always served by the local Ollama instance on the home server, never the GPU pod. All other types are served by the GPU pod Ollama instance.

Shared Contracts

The response envelope is used by every endpoint in the system. It wraps all success and error responses with a consistent outer shape so clients have a single contract to parse regardless of which endpoint they call.

classDiagram
    class GatewayResponse~T~ {
        T data
        GatewayError error
        ResponseMeta meta
    }

    class GatewayError {
        GatewayErrorCode code
        String message
    }

    class ResponseMeta {
        String requestId
        LocalDateTime timestamp
    }

    GatewayResponse --> GatewayError
    GatewayResponse --> ResponseMeta
    GatewayError --> GatewayErrorCode

Class Constraints

Class	Purpose	Key Constraints
`GatewayResponse`	Universal response envelope wrapping all Zoltraak API responses. Generic over the data payload type so all endpoints share the same outer shape while carrying their own specific data.	meta is always present on every response. `requestId` enables request tracing across logs.
`GatewayError`	Structured error detail included in the `GatewayResponse` envelope if the request fails	code references `GatewayErrorCode` Enum, message is human readable and suitable for display.
`ResponseMeta`	Request tracing and context metadata included in every response.	`requestId` is a UUID generated per request at the gateway entry point. timestamp is UTC ISO 8601.