Full Checklist

The Five Layers

Complete Checklist

1 — Database: NodeType Record

• NodeType row inserted with a unique typeCode (kebab-case, e.g. "send-slack-message")
• displayName set (shown in the node palette)
• category set (groups nodes in the sidebar)
• shape set: "rectangle" | "circle" | "diamond" (controls built-in renderer selection)
• icon set (Font Awesome class, e.g. "fa-solid fa-envelope")
• color set (hex string, used in node header background)
• ports array defined — each port has portKey, portType, isMainPort, isErrorPort, isRequired, isMultiple
• defaultConfig JSON set with default values for all configuration fields
• formId set (references the Atlas Form for this node's config panel) — set to 0 if no config needed
• isDeprecated: false confirmed
• NodeType record seeded via migration or seed script (not inserted manually)

2 — Atlas Form: Configuration UI

• Atlas Form created in the Forms system matching NodeType.formId
• All configuration fields defined (required/optional/default values)
• Credential fields use the credentialId field type (never raw secret strings)
• Form field keys exactly match the properties read by the backend executor via GetConfig<T>()
• Form validated in Atlas Form preview mode before linking

3 — Frontend: Custom Renderer (only if custom shape needed)

• New file created: packages/flow-studio-designer/src/components/Nodes/MyCustomNode.tsx
• Class extends BaseNode (import from ../Base/BaseNode)
• renderBody() implemented — not render()
• At least one CustomHandle (target) included
• At least one CustomHandle (source) included for non-terminal nodes
• Handle id props exactly match the portKey values in the NodeType ports array
• Error output handle uses isErrorPort={true} if node has error routing
• Execution status overlay implemented (reads this.designerMode.nodeStatuses)
• Component exported with withNodeHooks: export const MyCustomNode = withNodeHooks(MyCustomNodeClass)
• No withNodeHooks call duplicated in WorkflowCanvas.tsx (pre-wrapped at export)

4 — Frontend: Canvas Registration

• Renderer imported into WorkflowCanvas.tsx
• Entry added to the nodeTypes object: key = typeCode, value = imported renderer
• nodeTypes object is declared outside the component function (avoids re-mount bug)
• typeCode key matches the DB NodeType.typeCode character-for-character

5 — Backend: Executor

• C# class created implementing IProcessElementExecution
• TypeCode property returns the exact same string as the DB NodeType.typeCode
• Settings class created (inherits BaseNodeExecutorSettings) with properties matching Atlas Form field keys
• GetConfig<MySettings>(context) called to deserialise node configuration
• All secrets accessed via ICredentialResolver.GetPasswordAsync(credentialId) — never stored raw
• Happy path returns NodeExecutionResult.Success(outputData)
• Error path returns NodeExecutionResult.Failure(errorMessage) or throws for error-port routing
• Executor registered in the DI container (Transient) in the appropriate executor project
• Unit tests written for the executor covering success and error paths

TypeCode Must Match in All Three Places

// 1. NodeType DB record
typeCode: "send-slack-message"

// 2. WorkflowCanvas.tsx — nodeTypes key
const nodeTypes = {
  'send-slack-message': SlackMessageNode,  // <-- must match
}

// 3. Backend executor
public string TypeCode => "send-slack-message";  // <-- must match