Skip to main content

Development Checklist: N8N Killer Workflow Designer

✅ Phase 1: UX/Usability (Days 1-2)​

1.1 ExecModule Catalog & Schema​

  • Create execModuleCatalog.ts with all 20+ module schemas
  • Add ModuleSchema interface with form fields
  • Implement helper functions:
    • getModuleSchema(moduleType)
    • getModuleConfigSchema(moduleType)
    • validateModuleConfig(moduleType, config)
  • Add unit tests for catalog validation
  • Document module field types and validation rules

Modules to define schemas for:

  • Email (recipient, subject, body, attachments)
  • REST (URL, method, headers, body)
  • Stripe (API key, amount, customer)
  • AWS (region, service, operation)
  • Slack (channel, message, threadId)
  • SMS/Twilio (phone, message)
  • Webhook (URL, method, headers)
  • Database (connection, query)
  • Spreadsheet (file, sheet, range)
  • PDF (template, data)
  • Image Generation (prompt, model)
  • OpenAI (prompt, model, temperature)
  • Branching (condition, trueTarget, falseTarget)
  • Error Handler (errorType, action)
  • Delay (seconds)
  • Map (mapper function)
  • Filter (predicate)
  • Aggregate (aggregator function)
  • Transformer (transformation rules)
  • Logger (format, level)
  • Custom (className reference)

1.2 Unified ExecModule Configuration Editor​

  • Create ExecModuleConfigBuilder.tsx component
  • Support form field types:
    • Text input with validation
    • Email input
    • URL input
    • Number input
    • Textarea with placeholder
    • Dropdown (select)
    • Multi-select
    • JSON editor
    • API lookup (with typeahead)
    • Date/time picker
    • Color picker
  • Add error display and validation messages
  • Add field description and examples
  • Test component with all field types
  • Create ExecModuleConfigBuilder.test.tsx

1.3 Module Chaining Visualization​

  • Create ModuleChainViewer.tsx component
  • Show modules in execution order (sorted by moduleOrder)
  • Implement drag-to-reorder functionality
  • Update moduleOrder on drop
  • Show module status badges (ready, running, good, error)
  • Visual connectors between modules (arrows + labels)
  • Click to select/edit module
  • Create styles in ModuleChainViewer.css
  • Test drag-and-drop interactions
  • Create ModuleChainViewer.test.tsx

1.4 Task UX Improvements​

  • Update InspectorPanel.tsx to show module list
  • Add quick-edit button for each module
  • Add quick-delete button for each module
  • Integrate ModuleChainViewer into inspector
  • Show task-level settings (role, retry policy, timeout)
  • Add visual feedback for module execution status

1.5 API Lookup Component (Part of 1.2)​

  • Create ApiLookupField.tsx component
  • Implement typeahead search
  • Call backend QBE endpoint for data
  • Display results in dropdown
  • Allow user to select and populate field
  • Cache recent lookups
  • Create tests

✅ Phase 2: Server-Side Tightening (Days 2-3)​

2.1 Workflow Execution Service (ValkyrWorkflowService.java)​

Audit & Fixes:

  • Review executeTask() method
  • Ensure Hibernate.initialize() called on:
    • workflow.getTasks()
    • task.getModules()
    • Before passing to async thread
  • Fix lazy-loading in loadWorkflowSchedules()
  • Implement proper module data flow:
    • Parse module input/output mapping
    • Thread state between modules
    • Merge module output into workflow state
  • Implement branching module support:
    • Evaluate branch condition
    • Route to appropriate next task
    • Join converging branches
  • Implement parallel execution:
    • Detect "parallel": true in moduleData
    • Execute modules in same group concurrently
    • Wait for all to complete before continuing
  • Add comprehensive logging:
    • Log task start/completion
    • Log module execution
    • Log state transitions
    • Log execution time per module
  • Test with various workflow topologies

2.2 ExecModule Service (ValkyrExecModuleService.java)​

Create/Update/Delete:

  • Audit createExecModule() method
    • NEVER set ID (let JPA generate)
    • Set default role (ANONYMOUS)
    • Link to parent task
    • Save and return fresh object
  • Test creation without explicit ID
  • Test that ID is generated by JPA
  • Implement updateExecModule():
    • Validate configuration
    • Update only allowed fields
    • Persist changes
  • Implement deleteExecModule():
    • Remove from parent task
    • Delete module record
    • Clean up relationships

Configuration & Validation:

  • Implement validateModuleConfig():
    • Check required fields per module type
    • Validate field values (URLs, enums, etc.)
    • Return validation errors (not exceptions)
  • Implement getModuleConfigSchema():
    • Return JSON schema for frontend
    • Include validation rules
    • Include examples
  • Test validation for all module types

Testing:

  • Unit tests for CRUD operations
  • Integration tests with database
  • Test ID generation (should NOT be user-provided)
  • Test configuration validation

2.3 Task Service (ValkyrTaskService.java)​

CRUD Operations:

  • Audit createTask():
    • Initialize empty modules list
    • Don't set ID manually
    • Link to parent workflow
    • Save and return fresh object
  • Implement addModuleToTask():
    • Calculate new moduleOrder
    • Add to task.modules
    • Persist both task and module
  • Implement updateModuleOrder():
    • Re-calculate moduleOrder values
    • Persist all module updates
  • Implement removeModuleFromTask():
    • Remove from task.modules
    • Delete module record
    • Persist task

Testing:

  • Unit tests for all operations
  • Integration tests with Workflow
  • Test module ordering (float values)
  • Test cascade operations

2.4 Workflow Service (ValkyrWorkflowService.java - additional methods)​

CRUD Operations:

  • Audit createWorkflow():
    • NEVER set ID
    • Initialize empty tasks list
    • Set owner to current user
    • Save and return fresh object
  • Implement updateWorkflow():
    • Validate workflow structure
    • Update only allowed fields
    • Persist changes
  • Implement deleteWorkflow():
    • Delete all child tasks/modules
    • Delete workflow record
    • Clean up ACLs

Workflow Validation:

  • Implement validateWorkflow():
    • At least 1 task required
    • Each task has at least 1 module
    • All required fields filled
    • No cycles in task graph
    • Return validation errors

Testing:

  • Unit tests for validation
  • Integration tests for CRUD
  • Test ID generation
  • Test structure validation

✅ Phase 3: Data Lookup & API Integration (Days 3-4)​

3.1 REST API Lookup Service (Java)​

Create: RestApiLookupService.java

  • Maintain cache of known OasOpenAPISpec objects
  • Method: getApisByType() → list of REST APIs
  • Method: callApi(spec, endpoint, params) → response
  • Method: getEndpointSchema(spec, endpoint) → JSON schema
  • Cache responses for 1 hour
  • Implement error handling

3.2 REST API Lookup Component (TypeScript)​

Create: RestApiLookupComponent.tsx

  • Dropdown showing available REST APIs
  • Search/filter by API name
  • Select API → show available endpoints
  • Select endpoint → fetch schema
  • Show sample data from endpoint
  • Allow user to map fields
  • Test endpoint with sample query
  • Return selected values

3.3 API Browser Component​

Create: ApiBrowserComponent.tsx

  • List all available OasOpenAPISpec objects
  • Search by name/tag/category
  • Show endpoint details:
    • HTTP method
    • Path parameters
    • Query parameters
    • Request body schema
    • Response schema
  • Test endpoint with sample data
  • Copy endpoint URL / sample request
  • Show response data
  • Integrate with module configuration

3.4 QBE (Query By Example) Integration​

Backend: Add QBE endpoint for module inputs

  • GET /Workflow/qbe?example={...} → filtered workflows
  • Extend to all major entities (User, Task, etc.)
  • Return results as dropdown options

Frontend: Use in module configuration

  • EmailModule: search for User by email/name
  • REST module: query available endpoints
  • Stripe module: query customer database
  • etc.

✅ Phase 4: Workflow Lifecycle & Sync (Days 4-5)​

4.1 Create Workflow Flow​

Backend:

  • POST /Workflow endpoint
    • Accept Workflow with null ID
    • Validate required fields
    • Save via service (ID generated by JPA)
    • Return fresh object with ID set
    • Return 201 Created with Location header

Frontend:

  • Show "Create Workflow" modal
  • Get name, description from user
  • POST to /Workflow with no ID
  • On success, navigate to editor with ID from server response
  • Show error if creation fails

4.2 Edit Workflow Flow​

Frontend Redux:

  • Implement dirty-state tracking:
    • Track which fields changed
    • Show "unsaved changes" indicator
    • Prevent navigation without confirmation
  • Implement auto-save (debounced 2s):
    • On field change, set dirty flag
    • Debounce save operation
    • PATCH endpoint for partial updates
    • Show save status (saving, saved, error)
  • Implement update conflict detection:
    • Check workflow.updatedDate on server
    • If stale, show conflict dialog
    • Options: keep local, accept server, merge
    • Implement merge strategy

Backend:

  • PATCH /Workflow/{id} endpoint
    • Accept partial Workflow object
    • Validate changes
    • Check for conflicts (updatedDate)
    • Update and persist
    • Return updated object
  • Implement optimistic locking (updatedDate)

4.3 Workflow Validation​

Frontend:

  • Implement validateWorkflow():
    • At least 1 task
    • Each task has at least 1 module
    • All required fields filled
    • No cycles in graph
    • Return validation errors array
  • Show validation errors prominently
  • Disable save if validation fails
  • Show error details in UI

Backend:

  • Implement same validation server-side
  • Return 400 with validation errors if invalid
  • Include detailed error messages
  • Never save invalid workflows

✅ Phase 5: Testing & Quality (Days 5-6)​

5.1 Unit Tests​

Frontend:

  • execModuleCatalog.test.ts (20+ schemas)
  • ExecModuleConfigBuilder.test.tsx (all field types)
  • ModuleChainViewer.test.tsx (drag, reorder)
  • ApiLookupComponent.test.tsx (search, lookup)
  • ApiBrowserComponent.test.tsx (browse, test)
  • Redux tests (dirty state, auto-save)
  • Validation tests (workflow, modules)

Backend:

  • ValkyrWorkflowServiceTest.java
    • Test executeTask()
    • Test module data flow
    • Test branching
    • Test parallel execution
    • Test lazy-loading
  • ValkyrExecModuleServiceTest.java
    • Test ID generation (NO manual ID)
    • Test validation
    • Test CRUD operations
  • ValkyrTaskServiceTest.java
    • Test module ordering
    • Test add/remove operations
  • WorkflowControllerTest.java
    • Test endpoints
    • Test validation
    • Test error handling

5.2 Integration Tests​

Workflow Creation to Execution:

  • Create workflow via API
  • Add task to workflow
  • Add 3 modules to task with chaining
  • Configure each module with valid data
  • Save workflow
  • Retrieve workflow and verify structure
  • Execute workflow
  • Verify state transitions
  • Check execution results

Module Data Flow:

  • Module A outputs { orderId: "123" }
  • Module B receives and uses orderId
  • Module C receives merged state
  • Verify data threading through chain

5.3 E2E Manual Testing​

Create Workflow:

  • Open WorkflowStudio
  • Create new workflow
  • Name: "Test Email Campaign"
  • Save (should hit backend)
  • Verify ID assigned
  • Refresh page (should load from backend)

Add Task:

  • Add task "Send Emails"
  • Set role to SYSTEM
  • Save

Add Modules:

  • Add Email module
    • Configure recipient (use QBE to lookup User)
    • Configure subject
    • Configure body
    • Save
  • Add SMS module
    • Configure phone (use QBE)
    • Configure message
    • Save
  • Verify module chain shows both modules in order

Edit Workflow:

  • Change task name
  • Verify "unsaved changes" indicator
  • Modify Email subject
  • Verify auto-save after 2 seconds
  • Refresh page and verify changes persisted

Execute Workflow:

  • Run workflow
  • Monitor execution in console
  • Check module status updates
  • Verify final state

✅ Documentation & Deployment​

Documentation​

  • Update README.md with new features
  • Create WORKFLOW_DESIGNER_GUIDE.md
    • How to create workflows
    • How to configure modules
    • Module reference (all 20+)
    • Example workflows
  • Create DEVELOPER_GUIDE_WORKFLOW.md
    • Architecture overview
    • Adding new module types
    • Extending configuration editor
    • API reference
  • Update API documentation
  • Add ADR: "Workflow Module Configuration Builder"

Deployment Checklist​

  • All tests pass (80%+ coverage)
  • No console errors or warnings
  • No LazyInitializationException errors
  • No JPA ID generation issues
  • Performance: 100+ node workflows < 1s render
  • Mobile responsive (optional)
  • Accessibility: keyboard navigation, screen readers
  • Security: validate all inputs server-side
  • Security: ACL checks on all operations
  • Error handling: graceful failures with user-friendly messages

🎯 Success Criteria Checklist​

CriterionStatus
All 20+ module types have configuration forms❌
Modules snap together visually❌
Data flows correctly between modules❌
Workflows save/load reliably❌
No LazyInitializationException errors❌
No JPA ID generation issues❌
Users can create workflows in < 5 min❌
API lookups auto-complete user inputs❌
Server-side execution bulletproof❌
Tests cover 80%+ of code❌
Performance: 100+ nodes < 1s❌
Production-ready, enterprise-grade❌

Key Files Status​

FileStatusNotes
execModuleCatalog.ts❌ TODO20+ module schemas
ExecModuleConfigBuilder.tsx❌ TODOForm component
ModuleChainViewer.tsx❌ TODOChain visualization
ApiLookupComponent.tsx❌ TODOQBE lookup
ApiBrowserComponent.tsx❌ TODOAPI browsing
ValkyrWorkflowService.java⚠️ AUDITTighten execution logic
ValkyrExecModuleService.java⚠️ AUDITFix CRUD, validation
ValkyrTaskService.java⚠️ AUDITFix CRUD, module ordering
WorkflowController.java❌ TODOAdd trigger endpoint
All tests❌ TODO80%+ coverage

🚀 Timeline​

PhaseTasksDurationStatus
1UX improvements2 days❌ TODO
2Server-side tightening1 day❌ TODO
3API integration1 day❌ TODO
4Workflow lifecycle1 day❌ TODO
5Testing & QA1 day❌ TODO
TotalAll above6 days❌ TODO

Notes​

  • FOLLOW THE RULES IN valor_inference_prompt.txt section "N8N KILLER WORKFLOW DESIGNER INITIATIVE"
  • NEVER set IDs on new objects
  • ALWAYS use ThorAPI generated services
  • ALWAYS test before committing
  • ALWAYS document changes
  • DEADLINE: Production-ready, zero bugs