This post describes the state model I prefer for image workflows where the output represents a real place. The examples use virtual staging, but the same ideas apply to restoration, product mockups, background replacement, and other AI-assisted media tools.

Start with an immutable source asset

The first rule is simple: never let a generated result replace the uploaded file.

The source image should receive its own stable asset ID and immutable storage location. Everything derived from it should point back to that ID. This makes comparison, retry, audit, and alternate exports possible without relying on filenames or browser state.

A minimal record might contain:

type SourceAsset = {
  id: string;
  storageKey: string;
  mimeType: string;
  width: number;
  height: number;
  orientation: number;
  checksum: string;
  createdAt: string;
};

The checksum helps with accidental duplicate detection. Width, height, and orientation should be recorded after decoding, not inferred only from the extension. HEIC uploads and phone photos frequently expose orientation edge cases that otherwise appear later as “the model rotated my room.”

Model a job as stages, not a boolean

A field such as isProcessing works for a demo and fails quickly in production. An image may be uploaded, validated, normalized, queued, transformed, reviewed, exported, or rejected. Each stage can fail for a different reason and may have a different retry policy.

I prefer an explicit state machine:

type JobState =
  | "uploaded"
  | "validating"
  | "normalizing"
  | "queued"
  | "generating"
  | "review_required"
  | "approved"
  | "exporting"
  | "completed"
  | "failed";

State transitions should be written by the server. The client can request a transition, but it should not declare that a long-running job succeeded merely because a polling request returned.

A small event history makes support easier. “The image disappeared” becomes “normalization failed after a HEIC decode timeout,” which is a problem an engineer can act on.

Separate transformation intent from model parameters

Product inputs and model inputs should not be the same object.

A real-estate user thinks in terms such as room type, furniture style, whether existing movable furniture should be replaced, and whether the final listing file needs a disclosure label. The model may need masks, seeds, control weights, prompt fragments, and negative constraints.

Keep the product-level request stable:

type StagingIntent = {
  roomType: "living-room" | "bedroom" | "kitchen" | "dining-room" | "office";
  style: "standard" | "modern" | "coastal" | "farmhouse";
  replaceMovableFurniture: boolean;
  notes?: string;
};

Translate this intent into provider-specific parameters inside a versioned adapter. This prevents UI language from leaking into one vendor API and makes a model migration possible without rewriting stored jobs. Store the adapter version with every result because reproducing an output is difficult if the prompt builder changed silently.

Treat architectural preservation as validation

For virtual staging, visual attractiveness is not enough. The generated image is unusable if it changes windows, doors, flooring boundaries, built-ins, camera angle, or apparent room dimensions.

Some checks can be automated:

• compare edge maps between source and result;
• flag structural differences outside furniture regions;
• compare dimensions and crop bounds;
• detect missing windows or doors;
• measure whether major vanishing lines moved;
• verify that the result still represents the same room.

None of these checks is perfect. Uncertain results should move to review_required rather than hiding uncertainty behind a success badge.

The review interface should show source and result side by side or with a draggable comparison. A reviewer needs to inspect structure, reflections, furniture scale, blocked walkways, and visual artifacts. Approval is a meaningful state transition, not just a download click.

Make retries idempotent

Long-running image jobs will be retried. A user refreshes the page, a worker times out, or a webhook is delivered twice. Without an idempotency key, the system may charge twice, generate duplicate assets, or show several competing results.

A practical key can combine the source asset, normalized intent, adapter version, and a client-generated request ID. The API should return the existing job when it receives the same key again.

Worker retries need a different boundary. Retrying a failed upload is not the same as retrying a generation after a provider timeout. Record the stage that owns the retry and cap attempts per stage.

A property is a batch with shared context

Real listings contain multiple photos. Treating each one as an unrelated job makes consistency hard and the UI noisy.

A property-level object can hold shared decisions:

type PropertySession = {
  id: string;
  name: string;
  defaultStyle: StagingIntent["style"];
  disclosurePolicy: "none" | "virtually-staged" | "digitally-staged";
  assetIds: string[];
};

Each room still has its own job, but defaults and exports belong to the session. This lets a user stage the hero rooms first, keep one visual direction, and download a correctly named set instead of managing a pile of unrelated files.

The batch progress indicator should be derived from child states. “12 of 18 completed, 2 need review, 1 failed” is more useful than a single spinner.

Generate disclosure variants as exports

A disclosure label should not be burned into the only generated asset. Store the approved clean result, then create one or more export variants.

type ExportVariant = {
  resultId: string;
  resolution: "preview" | "4k";
  disclosureText?: string;
  storageKey: string;
};

This keeps a clean render available for permitted marketing uses while producing a clearly labeled version for listing channels that require it. It also allows wording or placement to change without rerunning the expensive transformation.

While building this workflow for Roomood, the separation turned out to be more important than adding another visual style. The useful outcome for an agent or real-estate photographer is a trustworthy, listing-ready file with a clear relationship to the original, not merely an attractive generated image.

Design the client around recovery

The browser should reconstruct the entire session from server state. Closing a tab must not lose an upload, erase a result, or leave a credit in an ambiguous state.

A resilient client:

1. creates the source asset before starting a job;
2. receives a job ID immediately;
3. polls or subscribes to server-owned state;
4. persists only lightweight UI preferences locally;
5. shows stage-specific failure messages;
6. offers a safe retry action;
7. reloads results from the property session.

This is less flashy than a progress animation, but it is what makes a tool dependable during a real listing deadline.

The central design principle

An AI image pipeline becomes trustworthy when every output answers four questions:

• Which source image did this come from?
• What did the user ask the system to change?
• Which model adapter and settings produced it?
• What checks and approvals happened before export?

If those answers live only in logs or in the user memory, the workflow is fragile. If they are part of the data model, retries, support, compliance, and future model changes become manageable.

The image model is one component. The product is the chain of custody around the image.

I have been thinking about this while building a small AI audio utility. This post is not a model write-up; it is a UI state write-up. The model can be excellent and the product can still feel broken if the surrounding state design is vague.

The first rule: do not hide the pipeline

For a short request, a spinner is usually fine. For audio work, a spinner quickly becomes a trust problem. Users need to know which part of the pipeline is happening.

A useful state machine can be simple:

• idle

• validating file

• uploading

• queued

• processing

• ready for preview

• exporting

• failed

The names do not matter as much as the separation. Uploading and processing are different states. A user can forgive waiting if the interface explains where the wait lives.

Validate before the upload

Client-side validation is not just a convenience. It prevents wasted time and avoids sending a file that will be rejected later.

For an audio upload flow, I usually want to check:

• file extension

• MIME type when available

• file size

• empty files

• obvious duration limits, if the browser can read metadata

The server still needs to validate everything again, but early validation improves the feel of the product. The error should also be specific. "This WAV file is too large" is much better than "Upload failed."

Make the job id a first-class object

Once the upload succeeds, the UI should stop thinking in terms of a file input and start thinking in terms of a job.

A job object might include:

• job id

• current status

• progress estimate, if reliable

• created time

• last updated time

• original filename

• available outputs

• recoverable error message

This object is useful for polling, retries, refresh recovery, and support debugging. It also keeps the UI from mixing temporary upload state with durable processing state.

Polling should be boring

Polling does not need to be clever. It needs to be predictable and kind to both the server and the user.

A reasonable pattern is:

• poll quickly for the first few seconds

• slow down after the job is clearly running

• stop polling when the job reaches a terminal state

• keep the last known status visible if a network request fails

• let the user retry the status check without re-uploading

The important part is not the interval. The important part is avoiding state jumps that make the user wonder whether the job disappeared.

Preview is part of completion

For audio tools, "processing complete" is not always the same as "the user is done." The user often needs to preview the output before deciding what to download.

That means the ready state should expose lightweight previews before pushing the user toward export. A waveform, duration, label, or short playback control can reduce uncertainty. It also helps users avoid downloading files they do not need.

Downloads need naming rules

Output naming sounds boring until it breaks. If a tool produces several audio files, names should be predictable:

• original-name-vocals.wav

• original-name-drums.wav

• original-name-bass.wav

• original-name-instrumental.wav

This is not just polish. It makes downstream editing easier, especially when users drag files into a DAW or send them to someone else.

Errors should preserve work

The worst failure mode is making the user start over without explaining why. A better failure state should keep the job context visible and separate recoverable errors from terminal ones.

For example, a temporary polling error should not erase the job. A processing failure should explain whether the user can retry, upload a different file, or contact support with a job id.

Where I applied this

I used this kind of state breakdown while working on my own browser-based stem separation project, TuneStems. The product goal is simple from the outside: upload a song and separate it into stems. The implementation lesson is that the surrounding states are just as important as the AI step itself.

For any web app that wraps a slow media job, I would treat the state model as product infrastructure. It is the part that keeps users oriented while the backend does the expensive work.