Singularity Logic Builder - Complete User Guide

🎯 What Is the Logic Builder?

The Singularity Logic Builder is a visual programming tool that lets you create executable backend logic flows using drag-and-drop blocks. Think of it as "visual coding" for your platform.

🚀 Complete Workflow: From Creation to Integration

Step 1: Create a Logic Flow

1. Navigate to /singularity/logic-builder
2. Click "New Flow" button
3. Name your flow (e.g., "User Registration Flow")
4. Start building!

Step 2: Build Your Flow (Drag & Drop)

A. Add Trigger Block (What Starts the Flow)

1. Open Block Library (left panel)
2. Find "Button Click" in Triggers category
3. Drag it onto the canvas
4. This is your starting point!

B. Add Logic Blocks (What Happens)

Popular blocks to add:

• Calculate: Do math operations
• Set Variable: Store data
• Storage Put: Save to database
• Widget Generate: Create UI components
• API Call: Fetch data from APIs

C. Connect Blocks (Define Flow)

1. Click the output port (green circle on right side of block)
2. Blue preview line appears following your mouse
3. Click the input port (green circle on left side of target block)
4. Connection created! Solid blue line appears

Step 3: Execute Your Flow

1. Click "Run" button (top of canvas)
2. Watch blocks animate as they execute
3. Execution Results panel opens (bottom)
4. View results in 4 tabs:
   • Output: Final results
   • Variables: All captured data
   • Execution Path: Timing and sequence
   • History: Past executions

Step 4: Use Your Flow (3 Ways)

Option A: Manual Testing

// Click "Run" button in UI
// Perfect for: Testing, debugging, prototyping

Option B: Trigger from Code

import { LogicExecutionEngineService } from '@libs-structural/singularity-lib';

// In your component
private executionEngine = inject(LogicExecutionEngineService);

async runMyFlow() {
  // Load flow from storage
  const flowId = 'flow_1760278137216';
  
  // Execute with optional inputs
  const result = await this.executionEngine.executeFlow(flowId, {
    variables: new Map([
      ['userId', '12345'],
      ['action', 'register']
    ])
  });
  
  console.log('Flow completed:', result.outputs);
  console.log('Variables:', result.variables);
}

Option C: Integrate with Events

// In your service or component
@Component({
  selector: 'app-user-registration',
  template: `
    <button (click)="handleRegister()">Register User</button>
  `
})
export class UserRegistrationComponent {
  private executionEngine = inject(LogicExecutionEngineService);
  
  async handleRegister() {
    // Execute your logic flow
    const result = await this.executionEngine.executeFlow('user-registration-flow', {
      variables: new Map([
        ['email', this.email],
        ['password', this.password]
      ])
    });
    
    if (result.success) {
      // Flow completed successfully
      const userId = result.outputs['userId'];
      this.router.navigate(['/dashboard']);
    } else {
      // Flow failed
      console.error('Registration failed:', result.error);
    }
  }
}

📋 Real-World Examples

Example 1: User Registration Flow

Blocks:

1. Button Click (Trigger) → User clicks "Register"

2. Validate Email (Condition) → Check email format

3. Storage Put (Action) → Save user to database

   key: 'user_' + email
   value: { email, password, createdAt: Date.now() }
   

4. Widget Generate (Action) → Create success message

   type: 'toast'
   config: { message: 'Registration successful!', type: 'success' }
   

5. Output (Result) → Return userId and redirect URL

Result:

• User data saved to storage-system
• Success toast shown
• Returns { userId: '123', redirectTo: '/dashboard' }

Example 2: Product Search Flow

Blocks:

1. API Call (Trigger) → When search button clicked

2. Storage Get (Action) → Fetch products from cache

   key: 'products_cache'
   

3. Calculate (Transform) → Filter by search term

   operation: 'filter'
   property: 'name'
   value: searchTerm
   

4. Widget Generate (Action) → Display results in table

   type: 'table'
   config: { data: filteredProducts, columns: ['name', 'price'] }
   

Result:

• Fast search using cached data
• Filtered results
• Auto-generated table widget

Example 3: Theme Switcher Flow

Blocks:

1. Button Click (Trigger) → Theme toggle button

2. Storage Get (Action) → Get current theme

   key: 'user_theme'
   

3. Calculate (Logic) → Toggle theme: light → dark, dark → light

4. Theme Apply (Action) → Apply new theme

   themeName: calculatedTheme
   

5. Storage Put (Action) → Save preference

   key: 'user_theme'
   value: newTheme
   

Result:

• Theme switches instantly
• Preference saved for next visit
• All components update automatically

🛠️ Available Block Types

Triggers (Start Points)

• Button Click: User interaction
• API Request: External API call
• Timer: Scheduled execution
• Event Listener: Custom events

Actions (Operations)

• Storage Put/Get/Remove: Database operations
• Widget Generate: Create UI components
• Module Load: Load application modules
• Theme Apply: Change themes
• API Call: External integrations

Logic (Decision Making)

• Condition: If/else logic
• Calculate: Math and transformations
• Loop: Iterate over data
• Variable Set/Get: Data management

Outputs (Results)

• Display Result: Show in UI
• Navigate: Change routes
• Emit Event: Trigger other systems

🎬 Execution Visualization

When you click "Run", watch the magic happen:

1. Block Highlighting (Real-Time)

   • 🟡 Yellow: Currently executing
   • 🟢 Green: Completed successfully
   • 🔴 Red: Error occurred

2. Connection Animation

   • Blue lines pulse as data flows

3. Live Variable Panel

   • See variables update in real-time
   • Inspect any value at any step

4. Step-Through Mode (Coming Soon!)

   • Execute one block at a time
   • Inspect state between steps
   • Perfect for debugging

💡 Best Practices

1. Name Things Clearly

// ❌ Bad
flow_12345

// ✅ Good
User Registration Flow

2. Break Down Complex Flows

Instead of one massive flow, create smaller, reusable flows:

• validate-email-flow
• save-user-flow
• send-welcome-email-flow

Then compose them!

3. Use Variables for Flexibility

// Instead of hardcoding:
Storage Put: key = '[email protected]'

// Use variables:
Storage Put: key = 'user_' + email

4. Add Error Handling

Always include:

• Condition blocks to check for errors
• Output blocks for error messages
• Fallback paths when things go wrong

5. Test with Different Inputs

Use the execution panel to test with:

• Valid data
• Invalid data
• Edge cases (empty strings, null values)

🔍 Debugging Tips

Problem: Flow Not Executing

Check:

• ✅ Does flow have a Trigger block?
• ✅ Are all blocks connected?
• ✅ Are required inputs provided?

Problem: Wrong Output

Fix:

1. Check Variables tab in Execution Results
2. See where data changed
3. Add Calculate blocks to transform data
4. Re-run and verify

Problem: Block Error

Fix:

1. Check Execution Path tab
2. Find the red (error) block
3. Read error message
4. Fix block configuration
5. Re-run

🚀 Advanced: Integrating with Your App

1. Create a Flow Service

// app/services/user-flows.service.ts
@Injectable({ providedIn: 'root' })
export class UserFlowsService {
  private executionEngine = inject(LogicExecutionEngineService);
  
  async registerUser(email: string, password: string) {
    return await this.executionEngine.executeFlow('user-registration-flow', {
      variables: new Map([
        ['email', email],
        ['password', password]
      ])
    });
  }
  
  async searchProducts(term: string) {
    return await this.executionEngine.executeFlow('product-search-flow', {
      variables: new Map([['searchTerm', term]])
    });
  }
}

2. Use in Components

@Component({
  selector: 'app-registration',
  template: `
    <form (ngSubmit)="onSubmit()">
      <input [(ngModel)]="email" type="email" />
      <input [(ngModel)]="password" type="password" />
      <button type="submit">Register</button>
    </form>
  `
})
export class RegistrationComponent {
  private userFlows = inject(UserFlowsService);
  
  email = '';
  password = '';
  
  async onSubmit() {
    const result = await this.userFlows.registerUser(this.email, this.password);
    
    if (result.success) {
      // Registration successful!
      const userId = result.outputs['userId'];
      this.router.navigate(['/dashboard']);
    } else {
      // Show error
      this.showError(result.error);
    }
  }
}

📊 What You Can Build

Backend Logic

• ✅ User authentication flows
• ✅ Data validation pipelines
• ✅ CRUD operations
• ✅ Complex business rules

UI Automation

• ✅ Dynamic widget generation
• ✅ Theme switching
• ✅ Form validation
• ✅ Navigation flows

Integrations

• ✅ API orchestration
• ✅ Module composition
• ✅ Event-driven workflows
• ✅ Real-time updates

Data Processing

• ✅ Filtering and sorting
• ✅ Calculations and transformations
• ✅ Batch operations
• ✅ Data aggregation

🎯 Next Steps

1. ✅ Create your first flow - Start with a simple button click → calculate → display
2. ✅ Save and name it - Give it a meaningful name
3. ✅ Execute and test - Click "Run" and check the results
4. ✅ Integrate into your app - Use LogicExecutionEngineService in your code
5. ✅ Build more flows - Experiment with different block combinations

🆘 Need Help?

Common Questions:

Q: How do I save a flow? A: Click "Save" button (top-right). Flow is auto-saved to storage-system with a unique ID.

Q: Can I reuse flows? A: Yes! Save flows with descriptive names, then execute them from anywhere in your app using LogicExecutionEngineService.executeFlow(flowId).

Q: How do I pass data between blocks? A: Use connections (blue lines). Data flows from output ports to input ports automatically.

Q: Can I edit a flow after saving? A: Yes! Load it from the flow list, make changes, and save again.

Q: How do I delete a flow? A: Click the 🗑️ icon next to the flow name in the flow list.

🔮 Coming Soon

• Step-Through Debugger: Execute one block at a time
• Breakpoints: Pause execution at specific blocks
• Flow Templates: Pre-built flows for common tasks
• Export to Code: Generate TypeScript from your flows
• Collaborative Editing: Build flows with your team in real-time

🎉 You're Ready!

The Logic Builder is your visual programming superpower. Start simple, experiment often, and build amazing things!

Remember: Every complex flow starts with one simple block. Just drag, connect, and execute! 🚀