⚡ Singularity Integration in Modular Universe

Overview

Singularity flows are now fully integrated with the Modular Universe, enabling space-builders to add custom behavior to their platforms without writing code.

Key Achievement: Flows execute automatically in both preview mode and deployed platforms!

Architecture

Flow Execution Pipeline

graph LR
    A[User Interaction] --> B[DOM Event]
    B --> C[WidgetRenderer]
    C --> D[FlowLoader]
    D --> E[LogicExecutionEngine]
    E --> F[Flow Blocks Execute]
    F --> G[FlowResultHandler]
    G --> H[Action: Navigate/Notify/Update]

Component Integration

┌─────────────────────────────────────────────────────────────┐
│                    BEHAVIOR PANEL                            │
│  - User attaches flows to widgets                           │
│  - Configures triggers (onClick, onLoad, etc.)              │
│  - Maps parameters                                          │
│  - Saves to widget.properties.flowTriggers                  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                  WIDGET RENDERER                             │
│  - Loads flows from storage (flow_* keys)                   │
│  - Binds flows to DOM events                                │
│  - Executes flows on triggers                               │
│  - Passes rich context to flows                             │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              LOGIC EXECUTION ENGINE                          │
│  - Executes flow blocks sequentially                        │
│  - Handles conditions, loops, branches                      │
│  - Calls platform integrations (HTTP, Storage, etc.)        │
│  - Returns result with data/error                           │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              FLOW RESULT HANDLER                             │
│  - Interprets flow results                                  │
│  - Performs actions (navigate, notify, update state)        │
│  - Handles errors gracefully                                │
└─────────────────────────────────────────────────────────────┘

Flow Attachment Workflow

Step 1: Create Flow in Singularity

// Example flow: Load products from API
const flow: LogicFlow = {
  id: 'load-products',
  name: 'Load Products',
  description: 'Fetch products from API and display',
  blocks: [
    {
      id: 'trigger',
      type: 'trigger',
      inputs: { eventType: 'onClick' }
    },
    {
      id: 'api-call',
      type: 'action',
      action: 'http',
      config: {
        method: 'GET',
        url: '/api/products'
      }
    },
    {
      id: 'transform',
      type: 'action',
      action: 'transform',
      config: {
        mapping: { products: '$.data' }
      }
    },
    {
      id: 'output',
      type: 'output',
      outputs: { products: '$.products' }
    }
  ],
  connections: [
    { from: 'trigger', to: 'api-call' },
    { from: 'api-call', to: 'transform' },
    { from: 'transform', to: 'output' }
  ]
};

// Save to storage
await storage.set('flow_load-products', flow);

Step 2: Attach Flow to Widget

1. In Modular Universe, select a widget
2. Open Behavior tab
3. Click Attach Flow
4. Select "Load Products" flow
5. Choose trigger: onClick
6. Map parameters (if needed)
7. Click Attach

Result:

widget.properties.flowTriggers = {
  'onClick': 'load-products'
};

Step 3: Flow Executes Automatically

When user clicks the widget in preview or deployed platform:

1. WidgetRenderer detects click event
2. Loads flow from storage (flow_load-products)
3. Executes flow with context
4. Flow makes API call
5. Transforms data
6. Returns result
7. FlowResultHandler processes result
8. UI updates automatically

Supported Triggers

Interaction Triggers

• onClick: User clicks element
• onHover: Mouse hovers over element
• onFocus: Element receives focus
• onBlur: Element loses focus
• onSubmit: Form is submitted

Lifecycle Triggers

• onLoad: Widget/module loads
• onUnload: Widget/module unloads
• onTimer: At specified interval

Data Triggers

• onChange: Value changes
• onDataChange: Data updates

Navigation Triggers

• onNavigate: Navigating to/from page

Custom Triggers

• custom: Custom event trigger

Flow Execution Context

Flows receive rich context for intelligent execution:

interface FlowExecutionContext {
  trigger: string;           // 'onClick', 'onLoad', etc.
  widget: Widget;            // Current widget
  event?: Event;             // DOM event (if applicable)
  moduleContext: {           // Parent module context
    spaceId: string;
    universeId: string;
    currentRoute: string;
    platformName: string;
  };
}

Usage in Flows:

// Access context in flow blocks
{
  type: 'action',
  action: 'http',
  config: {
    url: '/api/products',
    headers: {
      'X-Universe-Id': '{{context.moduleContext.universeId}}'
    }
  }
}

Flow Result Actions

Navigation

// Navigate to another page
{
  navigate: '/products/123'
}

// Navigate with query params
{
  navigate: {
    path: '/products',
    queryParams: { category: 'electronics' }
  }
}

Notifications

// Simple notification
{
  notification: 'Product added to cart!'
}

// Detailed notification
{
  notification: {
    message: 'Product added successfully',
    type: 'success',
    duration: 3000
  }
}

State Updates

// Update application state
{
  stateUpdate: {
    cartCount: 5,
    lastProduct: { id: 123, name: 'Product' }
  }
}

Reload Page

{
  reload: true
}

Open URL

// Open in new tab
{
  openUrl: 'https://example.com'
}

// Open with target
{
  openUrl: {
    url: 'https://example.com',
    target: '_blank'
  }
}

Download File

{
  download: {
    url: '/api/export/report.pdf',
    filename: 'report.pdf'
  }
}

Services

FlowLoaderService

Purpose: Load and cache flows from storage

Methods:

// Load single flow
const flow = await flowLoader.loadFlow('my-flow-id');

// Load all flows
const allFlows = await flowLoader.loadAllFlows();

// Batch load
const flows = await flowLoader.loadFlows(['flow1', 'flow2']);

// Invalidate cache
flowLoader.invalidateCache('my-flow-id');

FlowResultHandlerService

Purpose: Process flow execution results

Methods:

// Handle result
await flowResultHandler.handleResult(result, context);

// Automatically handles:
// - Navigation
// - Notifications
// - State updates
// - Errors

LogicExecutionEngineService

Purpose: Execute Singularity flows

Usage:

const result = await flowEngine.executeFlow(flow, context);

// Result structure:
{
  success: boolean;
  data?: any;
  error?: string;
  durationMs?: number;
}

Examples

Example 1: Button Click → Show Notification

Flow:

{
  id: 'show-welcome',
  blocks: [
    { type: 'trigger', inputs: { eventType: 'onClick' } },
    { 
      type: 'output', 
      outputs: { 
        notification: { 
          message: 'Welcome to our platform!', 
          type: 'success' 
        } 
      } 
    }
  ]
}

Attachment:

• Widget: Button
• Trigger: onClick
• Flow: show-welcome

Result: Clicking button shows success toast

Example 2: Page Load → Fetch Data

Flow:

{
  id: 'load-products',
  blocks: [
    { type: 'trigger', inputs: { eventType: 'onLoad' } },
    { 
      type: 'action',
      action: 'http',
      config: { method: 'GET', url: '/api/products' }
    },
    { 
      type: 'output',
      outputs: { products: '$.data' }
    }
  ]
}

Attachment:

• Widget: Product Grid
• Trigger: onLoad
• Flow: load-products

Result: Products load automatically when page opens

Example 3: Form Submit → API Call → Navigate

Flow:

{
  id: 'create-product',
  blocks: [
    { type: 'trigger', inputs: { eventType: 'onSubmit' } },
    { 
      type: 'action',
      action: 'http',
      config: { 
        method: 'POST', 
        url: '/api/products',
        body: '{{event.formData}}'
      }
    },
    { 
      type: 'condition',
      condition: '$.response.success === true'
    },
    { 
      type: 'output',
      outputs: { 
        notification: { message: 'Product created!', type: 'success' },
        navigate: '/products'
      }
    }
  ]
}

Attachment:

• Widget: Create Product Form
• Trigger: onSubmit
• Flow: create-product

Result: Form submission creates product, shows notification, navigates to products page

Best Practices

1. Flow Naming

• Use descriptive names: load-products, create-user, show-notification
• Prefix by category: api-load-products, ui-show-modal, nav-go-home

2. Error Handling

• Always include error blocks in flows
• Provide user-friendly error messages
• Log errors for debugging

3. Performance

• Use onLoad sparingly (executes on every page load)
• Cache API responses when possible
• Debounce frequent triggers (onChange, onScroll)

4. Parameter Mapping

• Map widget properties to flow inputs
• Use context variables ($event, $module, $user)
• Validate inputs in flows

5. Testing

• Test flows in Singularity first
• Test in preview mode before deployment
• Verify error handling

Future Enhancements

• Visual flow builder integrated into canvas
• Flow debugging panel in preview
• Flow performance analytics
• A/B testing for flows
• Flow versioning and rollback
• Shared flow library/marketplace

Last Updated: November 27, 2025 - 2:15 PM
Session ID: 11.25.2.9
Status: ✅ Complete and Production-Ready