Skip to main content

🎯 ExecModule Functionality Specification

Date: October 25, 2025
Status: 🚀 PRODUCTION IMPLEMENTATION
Scope: Complete ExecModule configuration, visualization, and execution

🎪 Overview​

ValkyrAI's workflow engine uses ExecModules as pluggable execution units. Each module needs:

  • ✅ Configuration UI - Visual forms for all parameters
  • ✅ Visual Representation - Special nodes/containers on canvas
  • ✅ Execution Logic - Backend implementation (already exists)
  • ✅ State Management - Redux integration for real-time updates

🔄 Control Flow Modules​

1. LooperModule (com.valkyrlabs.workflow.modules.control.LooperModule)​

Purpose: Advanced loop control with FOR, WHILE, FOR-EACH, DO-WHILE modes

Configuration Parameters:

interface LooperConfig {
  loopType: "FOR" | "WHILE" | "FOR_EACH" | "DO_WHILE";

  // FOR loop
  iterations?: number; // Number of iterations (default: 10)
  startIndex?: number; // Starting index (default: 0)

  // WHILE/DO_WHILE loop
  condition?: string; // Loop continuation condition

  // FOR_EACH loop
  collection?: string; // Path to collection (e.g., "workflow.state.items")
  itemVariable?: string; // Variable name for current item (default: "item")
  indexVariable?: string; // Variable name for current index (default: "index")

  // Common
  breakCondition?: string; // Exit loop early
  continueCondition?: string; // Skip to next iteration
  maxIterations?: number; // Safety limit (default: 1000)
  nested_task?: string; // Task ID to execute per iteration

  // Progress tracking
  trackProgress?: boolean; // Enable real-time progress (default: true)
  progressCallback?: string; // Webhook/endpoint for progress updates
}

Visual Representation:

  • Container Node with loop icon (🔄)
  • Progress Bar showing current iteration / total
  • Circular Progress arc around node
  • Iteration Counter badge
  • Break/Continue condition indicators
  • Child Tasks nested inside container with connecting lines

UI Components Needed:

  1. LooperConfigPanel.tsx - Configuration form
  2. LooperNode.tsx - Canvas visual (already exists, needs enhancement)
  3. LooperContainer.tsx - Container for nested tasks
  4. LooperProgressIndicator.tsx - Real-time progress display

Backend Integration:

  • ✅ Already implemented in Java
  • Needs: Progress webhooks, state persistence

2. MultiThreaderModule (com.valkyrlabs.workflow.modules.control.MultiThreaderModule)​

Purpose: Parallel execution with FAN-OUT, FAN-IN, RACE, and ALL strategies

Configuration Parameters:

interface MultiThreaderConfig {
  mode: "FAN_OUT" | "FAN_IN" | "RACE" | "ALL";
  maxThreads: number; // Thread pool size (default: 5)
  timeout: number; // Per-task timeout in ms (default: 30000)

  // Task selection
  parallel_tasks: string[]; // Array of task IDs to execute

  // Join strategy
  joinStrategy: "WAIT_ALL" | "WAIT_ANY" | "WAIT_FIRST";

  // Error handling
  retryOnFailure: boolean; // Retry failed tasks (default: false)
  maxRetries: number; // Max retry attempts (default: 3)
  continueOnError: boolean; // Continue if some tasks fail (default: false)

  // Output
  outputField: string; // Field name for results (default: "parallel_results")
  aggregateStrategy: "MERGE" | "ARRAY" | "FIRST" | "CUSTOM";
}

Visual Representation:

  • Container Node with parallel icon (⚡ or |||)
  • Thread Pool Indicator showing active threads
  • Branch Endpoints for each parallel task
  • Visual Container enclosing all parallel tasks
  • Progress Indicators for each branch
  • Join Point where branches reconverge
  • Color-coded branches (different colors for each thread)

UI Components Needed:

  1. MultiThreaderConfigPanel.tsx - Configuration form
  2. MultiThreaderNode.tsx - Canvas visual node
  3. MultiThreaderContainer.tsx - Container with branch visualization
  4. ThreadPoolIndicator.tsx - Active threads display
  5. ParallelBranchHandle.tsx - Special handles for branches

Backend Integration:

  • ✅ Already implemented in Java
  • Needs: Real-time progress tracking, thread state monitoring

📧 Communication Modules​

3. EmailModule (com.valkyrlabs.workflow.modules.email.EmailModule)​

Configuration:

interface EmailConfig {
  provider: "SMTP" | "SendGrid" | "Mailtrap" | "Mailersend";
  to: string | string[];
  from: string;
  subject: string;
  body: string;
  bodyType: "text" | "html";
  cc?: string | string[];
  bcc?: string | string[];
  attachments?: Array<{
    filename: string;
    path: string;
    contentType?: string;
  }>;
  template?: string; // Template ID for provider
  templateVars?: Record<string, any>;
}

UI: Standard form with rich text editor for body

4. WebhookReceiverModule (com.valkyrlabs.workflow.modules.WebhookReceiverModule)​

Configuration:

interface WebhookConfig {
  endpoint: string; // Auto-generated or custom
  method: "POST" | "GET" | "PUT" | "PATCH";
  authentication: "NONE" | "API_KEY" | "JWT" | "HMAC";
  secret?: string; // For HMAC validation
  headers?: Record<string, string>;
  responseTemplate?: string; // Response body template
  responseStatus?: number; // HTTP status code (default: 200)
}

Visual: Display generated webhook URL with copy button

🔌 Integration Modules​

5. RestApiModule (com.valkyrlabs.workflow.modules.rest.RestApiModule)​

Configuration:

interface RestApiConfig {
  url: string;
  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  headers?: Record<string, string>;
  query?: Record<string, string>;
  body?: any;
  authentication: {
    type: "NONE" | "BASIC" | "BEARER" | "API_KEY" | "OAUTH2";
    credentials?: {
      username?: string;
      password?: string;
      token?: string;
      apiKey?: string;
      headerName?: string;
    };
  };
  timeout?: number;
  retries?: number;
  responseMapping?: Record<string, string>;
}

UI: Visual API builder with test functionality

6. StripeModule (com.valkyrlabs.workflow.modules.stripe.StripeModule)​

Configuration:

interface StripeConfig {
  operation:
    | "CREATE_PAYMENT_INTENT"
    | "CREATE_CUSTOMER"
    | "CREATE_SUBSCRIPTION"
    | "REFUND";
  apiKey: string; // Encrypted
  amount?: number; // In cents
  currency?: string; // Default: 'usd'
  customerId?: string;
  productId?: string;
  priceId?: string;
  metadata?: Record<string, string>;
}

7. AWS Modules (S3, Lambda, SQS, SNS)​

S3 Configuration:

interface S3Config {
  operation: "UPLOAD" | "DOWNLOAD" | "LIST" | "DELETE";
  bucket: string;
  key: string;
  region: string;
  accessKeyId: string; // Encrypted
  secretAccessKey: string; // Encrypted
  contentType?: string;
  acl?: "private" | "public-read" | "public-read-write";
}

8. Social Media Modules​

LinkedIn, Twitter, Facebook, Instagram:

interface SocialMediaConfig {
  platform: "LINKEDIN" | "TWITTER" | "FACEBOOK" | "INSTAGRAM";
  operation: "POST" | "SCHEDULE" | "DELETE" | "GET_METRICS";
  accessToken: string; // Encrypted via OAuth
  content: {
    text?: string;
    media?: string[]; // URLs or file paths
    link?: string;
    hashtags?: string[];
  };
  schedule?: string; // ISO date or cron
  targetAudience?: string;
}

🔀 Transform Modules​

9. HandlebarsExecModule (com.valkyrlabs.workflow.modules.transform.HandlebarsExecModule)​

Configuration:

interface HandlebarsConfig {
  template: string; // Handlebars template
  data: Record<string, any>; // Context data
  helpers?: Record<string, string>; // Custom helpers (JS functions)
  partials?: Record<string, string>;
  outputField?: string;
}

UI: Code editor with syntax highlighting and preview

10. MapModule (com.valkyrlabs.workflow.modules.transform.MapModule)​

Configuration:

interface MapConfig {
  mappings: Array<{
    source: string; // JSONPath or field name
    target: string; // Output field name
    transform?: "UPPERCASE" | "LOWERCASE" | "TRIM" | "PARSE_JSON" | "TO_STRING";
    default?: any;
  }>;
  dropUnmapped?: boolean; // Remove fields not in mappings
}

🤖 AI Modules​

11. ImageGenModule (com.valkyrlabs.workflow.modules.ai.ImageGenModule)​

Configuration:

interface ImageGenConfig {
  provider: "DALL_E" | "STABLE_DIFFUSION" | "MIDJOURNEY";
  prompt: string;
  negativePrompt?: string;
  size: "256x256" | "512x512" | "1024x1024" | "1024x1792" | "1792x1024";
  quality: "standard" | "hd";
  style?: "natural" | "vivid";
  n: number; // Number of images
  apiKey: string; // Encrypted
  outputPath?: string; // Where to save
}

12. OpenAIModule (com.valkyrlabs.workflow.modules.ai.OpenAIModule)​

Configuration:

interface OpenAIConfig {
  model: "gpt-4" | "gpt-4-turbo" | "gpt-3.5-turbo";
  messages: Array<{
    role: "system" | "user" | "assistant";
    content: string;
  }>;
  temperature?: number; // 0-2
  maxTokens?: number;
  topP?: number;
  frequencyPenalty?: number;
  presencePenalty?: number;
  stop?: string[];
  apiKey: string; // Encrypted
}

🎨 UI Component Architecture​

Component Hierarchy​

WorkflowCanvas
├── StandardNode (task, branch, start, end)
├── LooperNode
│   ├── LooperHeader (with progress)
│   ├── LooperConfigPanel (modal)
│   └── LooperContainer
│       └── NestedTasks[]
├── MultiThreaderNode
│   ├── MultiThreaderHeader
│   ├── MultiThreaderConfigPanel (modal)
│   ├── ThreadPoolIndicator
│   └── MultiThreaderContainer
│       ├── ParallelBranch[1]
│       │   └── BranchTasks[]
│       ├── ParallelBranch[2]
│       │   └── BranchTasks[]
│       └── JoinPoint
└── ExecModuleNode (generic)
    ├── ModuleIcon
    ├── ModuleLabel
    └── ModuleConfigPanel (modal)

Shared Components​

  1. ExecModuleConfigModal.tsx - Base modal for all module configs
  2. ConfigFormField.tsx - Reusable form fields
  3. ConditionEditor.tsx - For break/continue conditions
  4. JSONPathSelector.tsx - Visual JSONPath builder
  5. EncryptedField.tsx - For API keys, secrets
  6. CodeEditor.tsx - Monaco editor for templates/code
  7. TestButton.tsx - Test module configuration

📊 State Management​

Redux Slices​

// workflowCanvasSlice.ts
interface CanvasState {
  nodes: Node[];
  edges: Edge[];
  selectedNodeId: string | null;
  looperStates: Record<string, LooperState>;
  multiThreaderStates: Record<string, MultiThreaderState>;
}

interface LooperState {
  nodeId: string;
  currentIteration: number;
  totalIterations: number;
  isRunning: boolean;
  progress: number; // 0-100
  breakConditionMet: boolean;
}

interface MultiThreaderState {
  nodeId: string;
  activeThreads: number;
  maxThreads: number;
  completedTasks: number;
  totalTasks: number;
  branchStates: Record<string, BranchState>;
}

interface BranchState {
  branchId: string;
  status: "pending" | "running" | "completed" | "failed" | "timeout";
  progress: number;
  result?: any;
  error?: string;
}

🎯 Implementation Priority​

Phase 1: Core Control Modules (Week 1)​

  • LooperModule configuration UI
  • LooperNode visual enhancement
  • LooperContainer with nested tasks
  • MultiThreaderModule configuration UI
  • MultiThreaderNode visual
  • MultiThreaderContainer with branches
  • Redux state management

Phase 2: Visual Polish (Week 1-2)​

  • Progress indicators
  • Thread pool visualization
  • Branch color coding
  • Container styling
  • Animations and transitions

Phase 3: Integration Modules (Week 2)​

  • REST API module UI
  • Email module UI
  • Webhook module UI
  • AWS modules UI
  • Social media modules UI

Phase 4: AI & Transform (Week 3)​

  • OpenAI module UI
  • Image generation UI
  • Handlebars editor
  • Map/transform UI

Phase 5: Testing & Documentation (Week 3-4)​

  • End-to-end tests
  • Visual regression tests
  • Performance optimization
  • User documentation
  • Video tutorials

🚀 Success Criteria​

Functional Requirements​

  • ✅ All modules have configuration UIs
  • ✅ Looper shows real-time progress
  • ✅ MultiThreader displays active threads
  • ✅ Containers visually distinct
  • ✅ Nested tasks render correctly
  • ✅ State persists across page reload

Non-Functional Requirements​

  • ✅ Configuration forms are intuitive
  • ✅ Visual feedback is immediate
  • ✅ Performance: < 16ms render time
  • ✅ Accessibility: Keyboard navigable
  • ✅ Mobile: Touch-friendly on tablets

📝 Notes​

  • All encrypted fields use @SecureField backend annotation
  • API keys never logged or exposed in client
  • Progress updates use WebSocket for real-time
  • Container nodes support zoom/pan
  • Nested tasks inherit parent auth context

Status: Ready for implementation
Owner: AI Coding Agent + Human Review
Timeline: 3-4 weeks for complete implementation

LET'S BUILD THE MOST FUNCTIONAL WORKFLOW ENGINE EVER! 🚀