Defining Graphs and Configurations

Cascaide graphs are best understood as node registries with emergent topology. Rather than explicitly declaring edges and state shape at the graph level, these are encoded within each node. This allows the execution graph to form dynamically at runtime.

This means the graph that runs is a consequence of execution, not a precondition for it.

You define your application using two graph types and two configuration types.

Client Workflow Graph

Client Workflow Graph tells the workflow engine what nodes are available. It only has meta data.


import { ClientWorkflowGraph } from "@cascaide-ts/core";
 
export const clientWorkflowGraph: ClientWorkflowGraph = {
    chat: { name: 'chat', isUINode: true ,env:'client'},
    searchAgentNode: { name: 'searchAgentNode', isUINode: false,env:'server' },
    searchToolNode: { name: 'searchToolNode', isUINode: false,env:'server' },
}

Type reference for ClientWorkflowGraph


export interface NodeDefinition {
  name: string;
  isUINode: boolean;
  env: 'client' | 'server';
}
 
type ClientWorkflowGraph = Record<string, NodeDefinition>;

Field	Description
`name`	Name of the node
`isUINode`	Whether this is a UI node
`env`	Where the node executes — `client` or `server`

💡

The key must match name in ClientWorkflowGraph.

Client Workflow Configuration


import Chat from "@/components/cascaide-ui/chat/chat"
import { ClientWorkflowConfig } from '@cascaide-ts/react';
import { clientWorkflowGraph } from "./graph";
 
export const clientWorkflowConfig: ClientWorkflowConfig = {
  clientWorkflowGraph: clientWorkflowGraph,
  uiComponentRegistry: {
    chat: Chat,
  },
};

ClientWorkflowConfig is made of two parts

Field	Description
`clientWorkflowGraph`	The graph defined above — tells the engine what nodes exist
`uiComponentRegistry`	A map of node names to their React UI components, used to render UI nodes

Types for reference


type ClientWorkflowConfig = {
  clientWorkflowGraph: ClientWorkflowGraph
  uiComponentRegistry: { [key: string]: React.ComponentType<any> };
};

💡

The key in uiComponentRegistry must match name in ClientWorkflowGraph.

Server Workflow Graph

ServerWorkflowGraph provides meta data and prep, exec, post functions of available nodes to the server side workflow engine.


 
export const serverWorkflowGraph: ServerWorkflowGraph = {
    searchAgentNode: {
      name: 'searchAgentNode',
      prep:  searchAgentNodePrep,
      exec: searchAgentNodeExec,
      post: searchAgentNodePost,
      isStreaming: true,
      isUINode:false,
      env:'server'
    },
    searchToolNode: {
      name: 'searchToolNode',
      prep: searchToolNodePrep,
      exec: searchToolNodeExec,
      post: searchToolNodePost,
      isUINode:false,
      isStreaming:false,
      env:'server'
    },
  };

Type reference


export interface ServerNodeDefinition<TPrep = any, TExec = any>
  extends NodeDefinition {
  isStreaming: false;
  prep: (cascadeContext: WorkflowContext, initialContext: any) => Promise<TPrep>;
  exec: (prepOutput: TPrep, controller?: CascadeController) => Promise<TExec>;
  post: (execOutput: TExec) => Promise<PostResult>;
}
 
export interface StreamingServerNodeDefinition<TPrep = any>
  extends NodeDefinition {
  isStreaming: true;
  prep: (cascadeContext: WorkflowContext, initialContext: any) => Promise<TPrep>;
  exec: (prepOutput: TPrep, controller?: CascadeController) => Promise<StreamConfig>;
  post: (execOutput: StreamingExecOutput) => Promise<PostResult>;
}
 
export type ServerWorkflowGraph = Record<
  string,
  ServerNodeDefinition<any, any> | StreamingServerNodeDefinition<any>
>;

Server Workflow Handler Configuration


import { WorkflowHandlerConfig } from '@cascaide-ts/server-next'
import {PostgresPersistor} from '@cascaide-ts/postgres-js';
import { sql } from '@/lib/connection';
import { serverWorkflowGraph } from './graph';
 
const workflowpersistor = new PostgresPersistor(sql);
const MAX_EXECUTION_TIME = 300000; 
const SAFE_BUFFER = 6000; 
 
export const serverWorkflowConfig:WorkflowHandlerConfig={
  workflowGraph:serverWorkflowGraph,
  persistor: workflowpersistor,
  maxExecutionTime: MAX_EXECUTION_TIME,
  safeBuffer: SAFE_BUFFER
}

Type reference


export interface WorkflowHandlerConfig {
  workflowGraph: ServerWorkflowGraph;
  persistor?: CascadePersistence; // The user passes their PostgresPersistor here
  maxExecutionTime?: number;
  safeBuffer?: number;
  extraMiddlewares?: Middleware[]; 
}

Field	Description
`workflowGraph`	The `ServerWorkflowGraph` — registers all server-side nodes and their prep/exec/post functions
`persistor`	Optional persistence layer for saving workflow state (e.g. `PostgresPersistor`). You set this to `undefined` in cascaide-lite
`maxExecutionTime`	Maximum time in milliseconds the workflow handler is allowed to run before it is forcibly stopped. In the example above this is 5 minutes (`300000ms`)
`safeBuffer`	A buffer in milliseconds subtracted from `maxExecutionTime` to give the handler time to cleanly wrap up before the hard cutoff. In the example above this is 6 seconds (`6000ms`)
`extraMiddlewares`	Any additional middlewares needed