Stage Data Model

Stage manages sessions, files, render state, snapshots, published apps, and Google scope declarations. Published apps may also carry linked GitHub repository metadata. All data is stored in Convex with the stage_ table prefix.

Session

A sandboxed environment with its own virtual filesystem and render state.

interface Session {
  createdAt: number;        // Unix timestamp (ms)
  lastAccessedAt: number;   // Unix timestamp (ms)
}

Sessions are identified by Convex-generated IDs (not nanoid).

SessionFile

A file within a session's virtual filesystem.

interface SessionFile {
  path: string;       // Virtual filesystem path (e.g., "/app/App.tsx")
  content: string;    // File content
  version: number;    // Auto-incrementing version number
  size: number;       // Content length in bytes
}

RenderState

The current render configuration and status for a session.

interface RenderState {
  entry: string;          // Entry point path (e.g., "/app/App.tsx")
  version: number;        // Render version (incremented on each trigger)
  error: string | null;   // Render error message, if any
  renderedAt: number | null; // Unix timestamp of last successful render
}

SessionStatus

A composite view returned by the status query.

interface SessionStatus {
  session: {
    createdAt: number;
    lastAccessedAt: number;
  } | null;
  render: {
    entry: string;
    version: number;
    error: string | null;
    renderedAt: number | null;
  } | null;
  files: Array<{
    path: string;
    version: number;
    size: number;
  }>;
}

AppSummary

A published Stage application in the app catalog.

interface AppSummary {
  sid: string;              // Shift ID
  name: string;             // App name
  description?: string;     // App description
  authorEmail?: string;     // Author's email
  authorName?: string;      // Author's display name
  status: string;           // "published" | "draft" | "archived"
  tags?: string[];          // Freeform tags
  sessionId: string;        // Associated session ID
  repository?: AppRepository;
  createdAt: number;        // Unix timestamp (ms)
  updatedAt: number;        // Unix timestamp (ms)
  lastDeployedAt: number;   // Unix timestamp (ms)
}

AppRepository

Optional repository metadata stored on a Stage app.

interface AppRepository {
  provider: "github";
  owner: string;
  name: string;
  fullName: string;         // owner/name
  url: string;              // Web URL
  visibility: "private" | "public" | "internal";
  defaultBranch?: string;
  remoteName?: string;      // usually "origin"
  linkedAt: number;         // Unix timestamp (ms)
  lastPushedAt?: number;    // Unix timestamp (ms)
  lastCommitSha?: string;
}

Google Scope Declaration

Stored scopes for a Stage session's end-user Google OAuth flow.

interface StageGoogleScopes {
  sessionId: string;
  scopes: string[];
  updatedAt: number;
}

Version Channel

Channels pin a specific app version to a deployment slot.

interface AppChannel {
  appSid: string;
  channel: "preview" | "production";
  appVersionSid: string;
  sessionId: string;
  branch?: string;
  commitSha?: string;
  updatedByEmail: string;
  updatedAt: number;
}

Version sources track how a version was created:

Source	Description
publish	Initial app publication
studio_deploy	Deploy from Studio session
feedback	Iteration from user feedback
promotion	Promoted from another channel

See Version Channels for the full deployment workflow.

Drive Recording

Stage sessions can store recording artifacts from drive operations.

interface DriveRecording {
  sessionId: string;
  fileId: string;
  filename: string;
  contentType: string;
  sizeBytes: number;
  storageId: string;
  recordedAt: number;
}

Recordings are validated at write time and referenced by transcription jobs for async processing.

Workflow Manifest

Published apps can declare manifest-backed workflow handlers in /app/shift.workflows.json.

interface WorkflowManifest {
  version: 1;
  workflows: Record<string, WorkflowDefinition>;
}

Workflow definitions can orchestrate:

• Google Sheets operations
• Billing item creation
• Pulse tracking
• Ledger audit events
• Communication message delivery
• Templated response payloads

Storage

Convex (default)

Stage uses Convex exclusively (no file-based storage). Tables use the stage_ prefix:

Table	Description
stage_sessions	Session records
stage_files	Virtual filesystem entries
stage_renderState	Render state per session
stage_snapshots	Point-in-time session snapshots
stage_apps	Published app catalog
stage_googleScopes	Stored Google OAuth scope declarations per session
stage_app_channels	Version channel records (preview/production per app)
stage_drive_recordings	Drive recording artifacts per session