Skip to content

Server Actions Map

Last refreshed: 2026-05-26

Shared Pattern

Shared types and helpers live in src/lib/server-actions.ts.

Use requireAuthContext, handleAction, handleBasicAction, ActionError, and ActionResult<T> for app mutations and reads that need authenticated workspace context.

  • handleAction: auth plus Mastra storage readiness for agent or workflow-backed actions.
  • handleBasicAction: auth plus error mapping only, for routes that only need the Payload Local API.
flowchart LR
  ui["🧑‍💻 Client panels"] --> action["Server action"]
  action --> auth["🔐 requireAuthContext"]
  action --> validate["✅ Validate input"]
  validate --> payload["📦 Payload Local API"]
  payload --> result["ActionResult<T>"]
  auth --> error["ActionError"]
  validate --> error

Action Files

Brand Kits

src/app/(frontend)/app/brand-kits/actions.ts

  • listBrandKits
  • upsertBrandKit
  • deleteBrandKit

Content Store

src/app/(frontend)/app/content-store/actions.ts

  • listSetVariants
  • listContentStoreItems
  • getContentStoreItemDetail

These catalog reads use handleBasicAction so dashboard and create-flow hydration do not depend on Mastra storage startup.

Create Flow

src/app/(frontend)/app/create/actions.ts

  • listVideoUseCases

This loader uses handleBasicAction because it only reads Payload data for route hydration.

Media

src/app/(frontend)/app/media/actions.ts

  • uploadMediaAsset

RAG

src/app/(frontend)/app/rag/actions.ts

  • listRagSources
  • getRagSourceDetail
  • updateRagSourceMetadata
  • enqueueRagIngestionJob
  • refineRagImageUserContext
  • refineRagVideoSectionDescription

RAG refinement actions use code-owned prompt builders in src/mastra/tools/rag/prompt-builders.ts and preserve normalized user_facing_description, asset_query, t0, and t1 return behavior.

The list/detail read actions use handleBasicAction; only refinement and ingestion-style actions keep handleAction.

Videos

src/app/(frontend)/app/videos/actions.ts

  • listPresentations
  • getPresentationDetail

These video list/detail reads intentionally use handleBasicAction so the pages do not depend on Mastra storage bootstrapping.

Presentation

src/app/(frontend)/app/presentation/actions.ts

  • getPresentation
  • generatePresentationDescription
  • generatePresentationNarrativePreview
  • continuePresentationFromNarrative
  • generatePresentationConfig
  • generatePresentationVideoScenesWithWorkflow
  • queuePresentationAudioGeneration
  • getPresentationGenerationStatus
  • previewPresentationConfig
  • generatePresentationVideo
  • updatePresentationScene
  • generatePresentationSceneAudioDraft
  • discardPresentationSceneVoiceoverDraft
  • commitPresentationSceneVoiceoverDraft
  • listPresentationSceneVisualOptions
  • refinePresentationSceneVoiceover
  • refinePresentationSceneCaption
  • regeneratePresentationSceneImage
  • generatePresentationSceneAudio

getPresentation and getPresentationGenerationStatus use handleBasicAction so /app/create/presentation hydration can load even if Mastra storage is unavailable. Workflow and agent-backed mutations continue to use handleAction.

The current create UI calls generatePresentationNarrativePreview first, then continuePresentationFromNarrative from the Go To Scene Details button. generatePresentationConfig and generatePresentationVideoScenesWithWorkflow remain compatibility paths and no longer read prompt records. Generated scene images are queued through presentation_generation_jobs; selectable visuals are manual Scene Editor replacement options, not automatic setup-stage source assignments.

Step 3 voiceover editing now uses a three-action draft cycle:

  • generatePresentationSceneAudioDraft creates temporary popup audio for the current draft text
  • discardPresentationSceneVoiceoverDraft removes abandoned popup audio
  • commitPresentationSceneVoiceoverDraft persists the popup draft into the scene and marks preview stale
flowchart TD
  createUi["Create presentation UI"] --> previewAction["generatePresentationNarrativePreview"]
  previewAction --> narrative["presentationVideoWorkflow to narrative-review"]
  narrative --> voPreview["VO Script Preview + approvedScript"]
  voPreview --> continueAction["continuePresentationFromNarrative"]
  continueAction --> workflow["resume presentationVideoWorkflow"]
  workflow --> imageJobs["presentation_generation_jobs"]
  imageJobs --> worker["presentation-worker Image Gen"]
  scenePanels["Scene edit panels"] --> editActions["voiceover/caption/image/pause actions"]
  editActions --> draftAudio["draft voiceover audio actions"]
  draftAudio --> previewRefresh["Generate Slides Preview / Generate VO Audio"]
  editActions --> promptBuilders["Code prompt builders"]
  promptBuilders --> editAgent["editAgent"]
  promptBuilders --> visualAgent["visualAgent"]
  ragUi["RAG library UI"] --> ragActions["RAG refine actions"]
  ragActions --> ragBuilders["RAG prompt builders"]

generatePresentationNarrativePreview now returns the line-by-line voiceoverPreview plus a preview-only approvedScript artifact. continuePresentationFromNarrative no longer accepts editable scene semantics from the UI at the review boundary; it resumes the workflow with approval and identity selection only, then runs post-approval narrative expansion inside the workflow.

Mutation Responsibilities

  • Validate active auth and workspace.
  • Validate user-provided relationship IDs against the active workspace.
  • Keep status/error fields explicit for generation, RAG, and assistant flows.
  • Keep action return shapes stable for client panels and polling.