Skip to main content

​
X402 Workflow Engine

The “X402” workflow is implemented in lib/x402.ts and used by the Idea → Intent → Platform → Payment → Execute → Completion flow. It manages:
  • Stages — WorkflowStage and transitions
  • Context — WorkflowContext with all stage outputs
  • Persistence — getWorkflowContextDB, updateWorkflowContextDB, createWorkflowContextDB (Prisma); in-memory getWorkflowContext, updateWorkflowContext, createWorkflowContext as fallback

​
Workflow Stages

type WorkflowStage =
  | 'idea_input'
  | 'intent_analysis'
  | 'platform_selection'
  | 'payment_processing'
  | 'execution'
  | 'completion';
StageAPI / TriggerMain data produced
idea_inputPOST /api/ideaidea, analysis, clarifyingQuestions
intent_analysisPOST /api/intentanswers, refinedRequirements
platform_selectionPOST /api/platformplatformOptions, selectedPlatform (later), supabaseIntegration
payment_processingPOST /api/payment or DodopaymentDetails (wallet/signature or dodoPaymentId)
executionPOST /api/executeexecutionResult
completion—UI only; uses executionResult

​
State Management

​
WorkflowContext

WorkflowContext in lib/x402.ts:
  • sessionId, currentStage, createdAt, updatedAt
  • idea, analysis, clarifyingQuestions, answers, refinedRequirements
  • platformOptions, selectedPlatform, supabaseIntegration
  • paymentDetails (e.g. walletAddress, amountScript, transactionSignature, paymentMethod, dodoPaymentId)
  • executionResult (agents, deliverables, review_passed, etc.)

​
Persistence

  • DB (preferred): getWorkflowContextDB, createWorkflowContextDB, updateWorkflowContextDB map to the Workflow model in prisma/schema.prisma. Some fields (e.g. platformOptions, executionResult) are not fully stored in DB; the code merges with in-memory when needed.
  • In-memory: workflowStore = new Map<string, WorkflowContext>(). Used when DB calls fail or for backwards compatibility.
API handlers typically: try DB first, on error fall back to in-memory. execute can rebuild a minimal context from prisma.workflow if the full context is missing.

​
Transitions

  • getNextStage(current) — Returns the next stage in order, or null at completion.
  • validateStageTransition(from, to) — Allows same stage or the immediate next stage only.

​
Error Handling

  1. Missing context — Idea: create context if new sessionId. Intent/Platform/Payment/Execute: return 400 with a message to restart or complete the previous stage; Execute may try to rebuild from DB.
  2. DB vs in-memory — On Prisma/connection errors, APIs log and fall back to in-memory; some fields (e.g. platformOptions) may be missing if only in memory.
  3. Execute-specific:
    • No refinedRequirements → build minimal from idea if present, else 400.
    • No selectedPlatform → 400.
    • Transaction signature invalid → 400.
    • Any requested agent disabled (isAgentEnabled) → 503 with list of disabled agents.
  4. AI (OpenRouter) errors — Propagated from processIdea, refineIntent, selectPlatform, executeX402Workflow; APIs return 500 with the error message.
  5. Platform templates — On per-file generation failure, generateFileContentWithAgent uses generateFileContent as a fallback so the run can still complete.