iris
Internal technical briefv0.1

System architecture · August 2026

iris is a durable system for creative generation.

The system coordinates model capabilities, asynchronous execution, storage, project-scoped context, and creative workflows. Its product surfaces are different entry points into the same generation substrate.

Core path
request → job → provider → asset
Ownership
user → project → media and context
Execution modes
inline image · durable video
An illustrated flow from a handwritten creative brief through structured system stages to a generated landscape.
Creative request → application-owned output

Intent becomes structured inputs, provider work, and durable media within the same system boundary.

01 / topology

One execution path, multiple product surfaces.

Agent, Studio, Sequences, and Director all converge on the same submission and finalization boundaries. This prevents provider behavior, asset handling, and job state from drifting by surface.

System topology
Product surfaces
AgentStudioSequencesDirector
submitGenerationnormalize · validate · reserve · persist job
Provider registrycapabilities · request builders · model catalog
BytePlusOpenAIGoogle
finalizecopy · persist asset · settle job · emit state
generationstored media + provenance

02 / job lifecycle

Images and video take different routes, then settle in one place.

Provider responses are not treated as app assets. An image can return within the originating request; video may complete later. In both cases, finalization creates the application-owned generation record exactly once.

Generation lifecycle
  1. 01Request acceptedAPI or server action receives prompt, params, references, caller, and project context.
  2. 02Request coercedModel capability validation resolves valid dimensions, reference limits, pricing, and provider payload.
  3. 03Job persistedstudio_job is written before provider work begins. Long-running work can now survive a closed browser.
  4. 04Provider execution
    imageprovider returns bytes or a ready URL in the request path
    videoprovider returns a task id; callback and job polling reconcile later
  5. 05Idempotent finalizationAsset bytes move to managed storage; the job transitions terminally; repeat callback or poll work cannot create a second generation.

03 / context and ownership

A project is the unit that holds media, memory, and workflow state together.

Project context is resolved server-side from the authenticated session or request. Clients and agents work with names and IDs that are scoped to their current project; they do not choose another user’s assets by supplying a storage URL.

Project context model
authenticateduser
projectbrief + access boundary
memorydurable facts
elements@handle references
generationsmanaged assets
workflowschats · sequences · films

04 / primary surfaces

Agent supplies guided intelligence. Studio supplies explicit control.

These are the two primary entry points into iris. They share the same media substrate, but they differ deliberately in how intent reaches it and how much of the system is exposed to a person at request time.

Agent

Guided intelligence over a durable session.

eve + AI SDK + iris tools

The Agent is not a direct chat completion wrapper. It is an eve agent whose channel establishes identity and trusted operating context before a model sees the turn. Its instructions define the creative operating policy; tools perform application actions; the model coordinates the two.

chat UIeve sessionchannel contextdynamic modelscoped tools
  1. 01
    Client session

    useEveAgent streams a durable eve session while the iris client persists its cursor and event log alongside the local chat record.

  2. 02
    Channel gate

    The eve channel authenticates the principal, claims the session owner, rate-limits sends, and rejects an app session that belongs to someone else.

  3. 03
    Trusted turn context

    The channel injects the available model catalog, permitted sizes and pricing, project memory, and recent assets as trusted metadata—not as user instructions.

  4. 04
    Dynamic model runtime

    defineAgent selects the configured OpenAI model per turn, applies low reasoning by default, caps output, and wraps every model call with server-side metering.

  5. 05
    Tools

    Tools execute generation, project memory, project assets, elements, and sequence planning. They resolve user and project scope on the server; the model never receives provider credentials.

Studio

Explicit media controls over the same runtime.

route + submitGeneration + jobs

Studio is the direct generation surface. It exposes model, ratio, size, reference, and quality choices while keeping validation, storage, billing, and async recovery below the UI. The selected controls are inputs to a normalized request, not a bypass around the system.

controlsAPI validationsubmitGenerationstudio_jobproviderfinalize
  1. 01
    Input contract

    The Studio route parses the request with zod, verifies the signed-in viewer and setup state, and permits only catalog model identifiers.

  2. 02
    Normalization

    submitGeneration resolves the provider model, coerces invalid parameters, validates managed upload URLs, and expands @element references within the model reference budget.

  3. 03
    Ownership and spend

    The same boundary verifies project ownership, creates an unnamed project when Studio needs one, rate-limits the caller, and reserves credits against normalized—not requested—parameters.

  4. 04
    Provider execution

    A provider adapter owns vendor-specific request formats. Images remain in the request until completion; video returns a durable provider task id.

  5. 05
    Job and asset state

    Jobs remain observable while work runs. Finalization copies bytes to managed storage, writes the generation record, settles billing, and resolves repeat callback or poll work idempotently.

05 / core records

The data model separates execution state from the resulting media.

A job answers “what is currently happening?” A generation answers “what is now available to the product?” Keeping those records distinct makes recovery, retries, provenance, and UI state explicit.

RecordResponsibilityKey state
project

The durable ownership boundary for a creative body of work.

brief, memory, chats, assets, sequences, films
studio_job

A provider request with queued, running, succeeded, or failed lifecycle state.

provider task id, normalized params, callback token, project scope
generation

A stored, project-owned media asset created once a job finalizes.

stable storage URL, media metadata, source model, provenance
element

A reusable reference set addressed by an @handle.

owner scope, reference images, kind, normalized handle
sequence / film

Higher-order composition records built over jobs and generations.

shots, frames, takes, ordering, timing, approval state

06 / system invariants

The boundaries that keep behavior consistent across the system.

01

One submission boundary

Every generation surface enters through submitGeneration, after parameter coercion and before a provider call.

02

One terminal path

finalize is the only route that makes media durable and job state terminal. Storage copy happens before settlement.

03

Provider-specific code stays adapter-local

The registry describes model capabilities; request builders handle vendor payloads, references, and response formats behind that contract.

04

Project context is server-resolved

Chats, assets, elements, and memory are scoped from trusted session context, not a model-provided user or project identifier.

05

Async recovery is a feature

Webhooks optimize completion, but client job reads reconcile provider state so work completes even if the callback or browser session is lost.

06

Spend state travels with the job

Cost estimation and credit reservation happen before execution; settlement or release follows the same terminal job transition.

07 / higher-order workflows

Sequences and Director compose work above the shared substrate.

They introduce workflow-specific records and views while retaining the same provider, job, generation, project, and billing paths described above.

SurfaceOwnsShared system dependencies
Sequences

draft, approval, keyframes, clip order, music selection

sequence actions · submitGeneration · project assets
Director

film graph, scene/shot editing, takes, budget projections

director domain · provider routing · shared finalization

Implementation map

lib/studio/submit.tssubmission boundarylib/studio/finalize.tsterminal job + asset pathlib/providers/registry.tsmodel capability cataloglib/projects/agent-context.tstrusted project resolutioncomponents/generation/*job and media UI primitives