Quick Reference: N8N Killer Workflow Designer

🚀 Get Started in 5 Minutes

What You Need to Know

Mission: Build the most intuitive workflow designer (better than N8N)
Platform: React + Spring Boot + PostgreSQL + ThorAPI
Key Challenge: Module chaining (snap together like LEGO)
Deadline: Production-ready, enterprise-grade

Three Core Files to Read

/Users/johnmcmahon/workspace/2025/valkyr/ValkyrAI/N8N_KILLER_WORKFLOW_INITIATIVE.md - Full context
/Users/johnmcmahon/workspace/2025/valkyr/ValkyrAI/valor_inference_prompt.txt - Development rules (search "N8N KILLER")
/Users/johnmcmahon/workspace/2025/valkyr/ValkyrAI/DEVELOPMENT_CHECKLIST.md - Task list

🔴 CRITICAL RULES (Violating = Severe Penalty)

Rule #1: NEVER Set IDs on New Objects

// ❌ WRONG - This breaks JPA
ExecModule m = new ExecModule();
m.setId(UUID.randomUUID());  // FORBIDDEN!
repo.save(m);  // JPA will throw error

// ✅ CORRECT - Let JPA generate the ID
ExecModule m = new ExecModule();
// Don't set ID
repo.save(m);  // JPA auto-generates UUID

Rule #2: Use ThorAPI Generated Services ONLY

// ❌ WRONG - Custom query
@Query("SELECT * FROM exec_module WHERE task_id = ?1")
List<ExecModule> findByTaskId(UUID taskId);

// ✅ CORRECT - Use generated repo
ExecModuleRepository repo;  // auto-generated by ThorAPI
List<ExecModule> modules = repo.findByTaskId(taskId);

Rule #3: Eager Load Before Async

// ❌ WRONG - LazyInitializationException in async thread
return CompletableFuture.supplyAsync(() -> {
    workflow.getTasks().forEach(...);  // CRASHES!
});

// ✅ CORRECT - Hydrate within transaction
@Transactional
public void loadSchedules() {
    List<Workflow> wfs = findAll();
    wfs.forEach(w -> {
        Hibernate.initialize(w.getTasks());
        w.getTasks().forEach(t -> Hibernate.initialize(t.getModules()));
    });
    // NOW safe to pass to async
}

Rule #4: Validate Server-Side, ALWAYS

// ✅ ALWAYS validate input on backend
@PostMapping("/Workflow")
public ResponseEntity<?> create(@RequestBody Workflow wf) {
    ValidationResult validation = validator.validate(wf);
    if (!validation.isValid()) {
        return ResponseEntity.badRequest().body(validation.errors);
    }
    // Safe to save
    return ResponseEntity.ok(repo.save(wf));
}

Rule #5: Error Handling in Modules (Not Exceptions)

// ✅ Return error maps, don't throw
@Override
public Map<String, Object> execute(Map<String, Object> input) {
    try {
        // Do work
        return Map.of("status", "success", "result", ...);
    } catch (Exception e) {
        // Return error map
        return Map.of("status", "error", "message", e.getMessage());
    }
}

📋 Phase Breakdown

Phase 1: UX (Days 1-2)

Build ExecModule catalog with 20+ schemas
Create unified config editor component
Add module chaining visualization
Implement drag-to-reorder

Phase 2: Server (Days 2-3)

Tighten workflow execution (proper data flow)
Fix ExecModule CRUD (no ID issues)
Fix Task service (module ordering)
Implement validation

Phase 3: APIs (Days 3-4)

REST API lookup service
QBE auto-complete for module inputs
API browser component

Phase 4: Lifecycle (Days 4-5)

Create workflow flow
Edit workflow with dirty-state tracking
Auto-save with debounce
Workflow validation

Phase 5: Testing (Days 5-6)

Unit tests (80%+ coverage)
Integration tests
E2E manual testing

🛠️ Common Patterns

Pattern: Create New Workflow (No ID!)

Backend:

@PostMapping("/Workflow")
public ResponseEntity<Workflow> create(@RequestBody Workflow wf) {
    if (wf.getId() != null) throw new BadRequest("ID must be null");
    Workflow saved = repo.save(wf);  // JPA sets ID
    return ResponseEntity.created(...).body(saved);
}

Frontend:

const workflow = { name: "My Workflow" }; // NO id
const result = await createWorkflow(workflow);
const workflowId = result.id; // Use server's ID

Pattern: Module Configuration Validation

interface FormField {
  name: string;
  type: "text" | "email" | "select" | "json" | "apiLookup";
  required: boolean;
  validation?: (value: any) => string | null;
}

const validateConfig = (fields: FormField[], config: any) => {
  const errors: Record<string, string> = {};

  fields.forEach((field) => {
    if (field.required && !config[field.name]) {
      errors[field.name] = `${field.name} is required`;
    }
    if (field.validation && config[field.name]) {
      const error = field.validation(config[field.name]);
      if (error) errors[field.name] = error;
    }
  });

  return { valid: Object.keys(errors).length === 0, errors };
};

Pattern: Async with Auth Context

final Authentication auth = SecurityContextHolder.getContext().getAuthentication();

return CompletableFuture.supplyAsync(() -> {
    SecurityContext ctx = SecurityContextHolder.createEmptyContext();
    ctx.setAuthentication(auth);
    SecurityContextHolder.setContext(ctx);

    try {
        // Do work
        persistState(workflow);
    } finally {
        SecurityContextHolder.clearContext();
    }
});

@Transactional(propagation = Propagation.REQUIRES_NEW)
void persistState(Workflow wf) {
    repo.save(wf);
}

Pattern: Module Data Flow

Map<String, Object> globalState = new HashMap<>();

// Module A execution
Map<String, Object> outputA = moduleA.execute(globalState);
globalState.putAll(outputA);  // Merge output

// Module B execution (receives merged state)
Map<String, Object> outputB = moduleB.execute(globalState);
globalState.putAll(outputB);  // Merge output

📊 Key Data Model

Workflow
├─ id (UUID, auto-generated by JPA)
├─ name (String)
├─ description (String)
├─ status (ACTIVE, PAUSED, DRAFT, ERROR)
├─ createdDate (DateTime)
├─ updatedDate (DateTime, for conflict detection)
└─ tasks: List<Task>
    ├─ id (UUID, auto-generated)
    ├─ workflowId (FK)
    ├─ name (String)
    ├─ role (SYSTEM, ASSISTANT, USER)
    ├─ taskOrder (Float: 1.0, 2.0, 3.0...)
    ├─ status (RUNNING, STOPPED, READY, ERROR)
    └─ modules: List<ExecModule>
        ├─ id (UUID, auto-generated)
        ├─ taskId (FK)
        ├─ name (String)
        ├─ className (String: com.valkyrlabs.workflow.modules.*)
        ├─ moduleType (String: Email, REST, Stripe, etc.)
        ├─ moduleOrder (Float: 1.0, 2.0, 2.5...)
        ├─ moduleData (JSON string with config)
        ├─ status (READY, RUNNING, GOOD, ERROR, WARNING)
        ├─ config (Map<String, Object>, persisted as JSON)
        └─ integrationAccount (Optional FK)

Key: Module execution order is determined by moduleOrder (float), not insertion order.

🎨 Component Tree

WorkflowStudio (main)
├─ WorkflowCanvas (ReactFlow)
│  ├─ TaskNode (task with nested modules)
│  │  ├─ ModuleNode (each module)
│  │  └─ ModuleChainViewer (show chain in inspector)
│  └─ TaskEdges
├─ FloatingExecModulesToolbar (palette)
├─ InspectorPanel (right side)
│  ├─ SelectedNodeDetails
│  ├─ ModulesList (with drag-reorder)
│  └─ ExecModuleEditModal
│     └─ ExecModuleConfigBuilder (form)
└─ BottomConsole (logs)

🔗 File Locations

Frontend (TypeScript/React)

web/typescript/valkyr_labs_com/src/
├─ components/WorkflowStudio/
│  ├─ execModuleCatalog.ts                (NEW - schemas)
│  ├─ ExecModuleConfigBuilder.tsx         (NEW - form)
│  ├─ ModuleChainViewer.tsx               (NEW - chain viz)
│  ├─ ApiLookupComponent.tsx              (NEW - QBE)
│  ├─ ApiBrowserComponent.tsx             (NEW - API browser)
│  ├─ index.tsx                           (MODIFY)
│  ├─ ExecModuleEditModal.tsx             (MODIFY)
│  ├─ InspectorPanel.tsx                  (MODIFY)
│  └─ WorkflowCanvas.tsx                  (MODIFY)
└─ redux/features/workflows/
   ├─ workflowSlice.ts                    (MODIFY - dirty state)
   └─ WorkflowService.ts                  (MODIFY - auto-save)

Backend (Java)

valkyrai/src/main/java/com/valkyrlabs/
├─ workflow/service/
│  ├─ ValkyrWorkflowService.java          (MODIFY)
│  ├─ ValkyrExecModuleService.java        (MODIFY)
│  ├─ ValkyrTaskService.java              (MODIFY)
│  └─ WorkflowValidator.java              (NEW)
├─ workflow/controller/
│  └─ WorkflowController.java             (MODIFY)
└─ workflow/config/
   └─ ExecModuleSchemaProvider.java       (NEW)

🧪 Testing Quick Start

Frontend Test Template

import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import ExecModuleConfigBuilder from "./ExecModuleConfigBuilder";

describe("ExecModuleConfigBuilder", () => {
  it("should render form fields for module type", () => {
    const module = { className: "EmailModule", moduleData: "{}" };
    render(<ExecModuleConfigBuilder module={module} onChange={jest.fn()} />);

    expect(screen.getByLabelText("Recipient Email")).toBeInTheDocument();
    expect(screen.getByLabelText("Subject")).toBeInTheDocument();
  });

  it("should validate required fields", async () => {
    const module = { className: "EmailModule", moduleData: "{}" };
    const onChange = jest.fn();

    render(<ExecModuleConfigBuilder module={module} onChange={onChange} />);

    const saveButton = screen.getByText("Save");
    await userEvent.click(saveButton);

    expect(screen.getByText("Recipient Email is required")).toBeInTheDocument();
  });
});

Backend Test Template

@SpringBootTest
@Transactional
class ValkyrWorkflowServiceTest {
    @Autowired
    private ValkyrWorkflowService workflowService;

    @Autowired
    private WorkflowRepository workflowRepo;

    @Test
    void testCreateWorkflowGeneratesId() {
        Workflow wf = new Workflow();
        wf.setName("Test Workflow");
        // DON'T set wf.setId(...)

        Workflow saved = workflowService.saveOrUpdate(wf);

        assertThat(saved.getId()).isNotNull();
        assertThat(workflowRepo.findById(saved.getId())).isPresent();
    }

    @Test
    void testExecuteTaskWithModuleChain() {
        // Create workflow with 2 modules
        Workflow wf = createTestWorkflow();
        Task task = wf.getTasks().get(0);

        // Execute
        BranchOutcome result = workflowService.executeTask(task, new HashMap<>(), ...);

        assertThat(result.status).isEqualTo("success");
        assertThat(result.state).containsEntry("moduleAOutput", "value");
    }
}

🚨 Common Mistakes to Avoid

❌ Wrong	✅ Correct
`m.setId(UUID.randomUUID())`	Leave ID null, let JPA generate
Custom `@Query` in repo	Use generated repo methods
Access lazy collections in async	`Hibernate.initialize()` first
Throw exceptions in modules	Return error maps
Trust client validation	Always validate on server
Set relationships manually	Use repository methods
No error handling	Handle all exceptions
No tests	Write tests first
No documentation	Document as you code
Hardcode secrets	Use environment variables

📈 Success Metrics

✅ = Complete and tested
⚠️ = In progress
❌ = Not started

Metric	Status	Target
Module config forms	❌	20+ types
Module chaining works	❌	Visual + functional
Data flows correctly	❌	Between all modules
Create workflow works	❌	No ID errors
Edit workflow works	❌	Dirty tracking, auto-save
Workflows execute	❌	All topologies
Tests pass	❌	80%+ coverage
No LazyInit errors	❌	Zero occurrences
Production ready	❌	Ready to deploy

🎯 Next 3 Steps

Today: Read all three files (N8N_KILLER, valor_inference_prompt, checklist)
Tomorrow: Start Phase 1 - Build execModuleCatalog with 20+ schemas
Day 3: Build ExecModuleConfigBuilder component

💬 Questions?

Refer to:

Rules: valor_inference_prompt.txt section "N8N KILLER WORKFLOW DESIGNER INITIATIVE"
Architecture: N8N_KILLER_WORKFLOW_INITIATIVE.md
Tasks: DEVELOPMENT_CHECKLIST.md
Code Examples: IMPLEMENTATION_ROADMAP_DETAILED.md

Remember: Every rule is there for a reason. Follow them to the letter.

🚀 Get Started in 5 Minutes​

What You Need to Know​

Three Core Files to Read​

🔴 CRITICAL RULES (Violating = Severe Penalty)​

Rule #1: NEVER Set IDs on New Objects​

Rule #2: Use ThorAPI Generated Services ONLY​

Rule #3: Eager Load Before Async​

Rule #4: Validate Server-Side, ALWAYS​

Rule #5: Error Handling in Modules (Not Exceptions)​

📋 Phase Breakdown​

Phase 1: UX (Days 1-2)​

Phase 2: Server (Days 2-3)​

Phase 3: APIs (Days 3-4)​

Phase 4: Lifecycle (Days 4-5)​

Phase 5: Testing (Days 5-6)​

🛠️ Common Patterns​

Pattern: Create New Workflow (No ID!)​

Pattern: Module Configuration Validation​

Pattern: Async with Auth Context​

Pattern: Module Data Flow​

📊 Key Data Model​

🎨 Component Tree​

🔗 File Locations​

Frontend (TypeScript/React)​

Backend (Java)​

🧪 Testing Quick Start​

Frontend Test Template​

Backend Test Template​

🚨 Common Mistakes to Avoid​

📈 Success Metrics​

🎯 Next 3 Steps​

💬 Questions?​