Project Lifecycle

Projects in Studio carry two pieces of state worth understanding: a project status that says where the project is in its life, and an instance status for each environment the project ships to. This page walks through both.

Project statuses#

A project lives in one of three states:

Status	Meaning
draft	Created but not yet deployed. The repo exists, the editor works, but no environment has the latest.
active	At least one instance has the project deployed. Editable, live, and the default state for the bulk of a project's life.
archived	Read-only. The repo is preserved, the project is hidden from the workspace dashboard, and no deploys are accepted.

A new project starts as draft. The first successful deploy promotes it to active. Archiving (from Workspace settings → Danger zone) flips it to archived, which is reversible — you can unarchive and pick up where you left off.

Instance statuses#

A single project can target multiple environments — typically Dev, Staging, UAT, and Prod. Each is an instance with its own status:

Status	Meaning
idle	Instance exists but isn't currently deploying. The most common steady state.
deploying	A deploy is in progress. The instance pulses in the UI; new deploys queue.
active	The last deploy succeeded and the instance is running.
error	The last deploy failed. The previous version stays live; the next deploy retries.

You see all instances on the project home (/p/[id]). Each row shows status, URL, who's currently editing in Studio, and a per-instance action menu (deploy, promote, view history, rollback).

The standard journey#

1. Create

   Pick an on-ramp: Build with AI, Migrate, or Connect. Studio scaffolds a project shell, opens the editor, and (for the first two) drops you into a draft branch with the AI's initial work staged for review.

2. Edit

   Iterate. The AI proposes patches, you accept the ones that move the project forward, you reject or re-prompt the ones that don't. Files change in-browser only; nothing has shipped yet.

3. First deploy

   Hit Deploy with a target instance selected. Studio commits the dirty files to the connected GitHub repo, then triggers CloudShell to build and deploy. The instance flips idle → deploying → active. The project flips draft → active.

4. Promote between environments

   Once Dev is happy, promote to Staging (or further). The project home's per-instance menu has a Promote to next instance action that copies the deploy artefact forward without rebuilding.

5. Live editing

   Most of the project's life is here. Workspace members open Studio, make changes, deploy. Liveblocks lets two people edit the same file at once. Activity is captured in the project's Activity feed — every deploy, edit session, member change, comment, and rollback shows up.

6. Roll back (when needed)

   If a deploy goes bad, the instance menu's Deploy history dropdown lists every prior deploy with its commit and timestamp. Rollback redeploys a previous revision; the instance status walks the same deploying → active path.

7. Archive

   When the project is done, Workspace settings → Danger zone → Archive sets the status to archived. The repo is preserved; deploys are blocked; the project hides from the dashboard. Unarchiving reverses this.

What triggers each transition#

Transition	Triggered by
draft → active	First successful deploy of any instance.
Instance idle → deploying	POST /api/deploy (Deploy button, Promote action, Rollback).
Instance deploying → active	CloudShell reports deploy success.
Instance deploying → error	CloudShell reports deploy failure. The previous version stays live.
active → archived	Workspace settings → Danger zone → Archive.
archived → active	Unarchive action (same place).

Where state lives#

Project and instance status types are defined in lib/projects.ts. The deploy route at app/api/deploy/route.ts streams status events back to the deploy panel as the deploy progresses. The activity feed (/p/[id]/activity) reads the same event stream after the fact.

Related#

• Project workspace reference
• How Studio Works
• Publish a project