Flow Composer

Visual canvas for connecting logic flows

Flow Composer

The Flow Composer is a powerful visual tool for connecting entire logic flows together to create complex, large-scale applications. It's like Figma for logic - a beautiful, intuitive canvas where you can compose sophisticated systems from reusable building blocks.

Overview

While the Logic Builder works at the block level (individual operations), the Flow Composer works at the flow level (complete workflows). This allows you to:

Getting Started

Opening Flow Composer

  1. Navigate to Singularity in the main menu
  2. Click on Flow Composer
  3. Select or create a new composition

Your First Composition

  1. Create a New Composition

    • Click the "New" button in the header
    • Give your composition a meaningful name

  2. Add Flows to Canvas

    • Browse available flows in the left sidebar
    • Drag a flow onto the canvas
    • Position it where you want

  3. Connect Flows

    • Click an output port (right side) on one flow
    • Click an input port (left side) on another flow
    • A connection line is created

  4. Save Your Work

    • Click the "Save" button in the header
    • Your composition is stored and can be loaded later

Canvas Interactions

Mouse Controls

Action Control
Pan canvas Middle-click drag OR Shift + left-click drag
Zoom in/out Mouse wheel
Add flow Drag from library
Select flow Left-click
Multi-select Ctrl + left-click
Connect flows Click output port → click input port

Keyboard Shortcuts

Shortcut Action
Ctrl+Z Undo
Ctrl+Y or Ctrl+Shift+Z Redo
Delete Remove selected nodes
Ctrl+A Select all nodes
Ctrl+S Save composition (when implemented)

Canvas Controls

Located in the bottom-right corner:

Flow Nodes

Understanding Flow Nodes

Each flow node on the canvas represents a complete logic flow:

Node States

Connections

Creating Connections

  1. Click an output port (right side) on the source flow
  2. Move cursor to input port (left side) on the target flow
  3. Click the input port to complete the connection

Connection Types

Connection Validation

The system automatically validates connections:

Removing Connections

Working with Compositions

Creating a Composition

// Compositions are automatically created when you:
// 1. Click "New" button
// 2. Add first flow to empty canvas

Saving a Composition

Loading a Composition

  1. Click "Load" button in header
  2. Select from list of saved compositions
  3. Composition loads with all nodes and connections

Cloning a Composition

  1. Open the composition you want to clone
  2. Click "Clone" in the actions menu
  3. A copy is created with "(Copy)" appended to the name

Exporting/Importing

Export

// Export to JSON file
const json = await compositionService.exportComposition(compositionId);
// Download or share the JSON

Import

// Import from JSON file
await compositionService.importComposition(jsonString);

Advanced Features

Multi-Universe Support

Compositions can reference flows from different universes:

// Flows are tagged with universeId
// You can mix flows from multiple universes
// Great for reusing logic across projects

Execution Orchestration

Execute an entire composition:

  1. Select the composition
  2. Click "Execute" button
  3. Watch flows execute in sequence
  4. View results in execution panel

Undo/Redo

Grid Snapping

Best Practices

Organization

  1. Group Related Flows: Keep flows that work together close
  2. Use Categories: Color-code by category
  3. Name Meaningfully: Clear names help understanding
  4. Add Descriptions: Document what each flow does

Performance

  1. Limit Complexity: Keep compositions under 20 flows
  2. Optimize Flows: Each flow should be efficient
  3. Avoid Cycles: Circular dependencies cause issues
  4. Test Incrementally: Test as you build

Reusability

  1. Create Generic Flows: Make flows reusable
  2. Parameterize Inputs: Use flow inputs for flexibility
  3. Document Interfaces: Clear input/output contracts
  4. Version Control: Use Git for composition backups

Integration with Other Systems

Space-Map Integration

// Get logic statistics for a universe
const stats = await spaceMapIntegration.getUniverseLogicStats(universeId);
// { flowCount: 5, compositionCount: 2, blockCount: 23 }

// Navigate to flow composer from universe detail
const url = spaceMapIntegration.getFlowComposerUrl(universeId);
this.router.navigateByUrl(url);

Editor Integration

// Execute composition from widget event
const result = await editorIntegration.executeCompositionFromWidget(
  compositionId,
  eventData,
  { widgetId, pageId, universeId }
);

Common Workflows

Building a Data Pipeline

  1. Add a Data Source flow
  2. Add Transform flows for processing
  3. Add a Data Sink flow for storage
  4. Connect them in sequence
  5. Test with sample data

Creating a User Authentication System

  1. Add Login Form flow
  2. Add Validation flow
  3. Add Database Check flow
  4. Add Session Creation flow
  5. Connect with error handling

Implementing a Workflow

  1. Add Trigger flow (e.g., button click)
  2. Add Business Logic flows
  3. Add Notification flow
  4. Add Logging flow
  5. Connect with branching logic

Troubleshooting

Canvas Issues

Problem: Canvas is frozen or unresponsive

Problem: Can't zoom or pan

Connection Issues

Problem: Can't create connection

Problem: Connection shows as invalid

Performance Issues

Problem: Canvas is slow with many nodes

Problem: Execution takes too long

Tips & Tricks

Productivity

Visualization

Collaboration

API Reference

FlowComposerComponent

// Key methods
async addFlowNode(flow: LogicFlow, position: { x: number; y: number })
async createConnection(sourceNodeId, sourcePortId, targetNodeId, targetPortId)
async saveComposition()
async loadComposition(compositionId: string)
undo()
redo()

FlowCompositionService

// CRUD operations
async createComposition(data: Partial<FlowComposition>): Promise<FlowComposition>
async getComposition(id: string): Promise<FlowComposition | null>
async updateComposition(id: string, updates: Partial<FlowComposition>)
async deleteComposition(id: string)
async listCompositions(filters?: { universeId?: string })

// Node management
async addNode(compositionId, flowId, position)
async removeNode(compositionId, nodeId)

// Connection management
async addConnection(compositionId, sourceNodeId, sourcePortId, targetNodeId, targetPortId)
async removeConnection(compositionId, connectionId)

// Advanced
async cloneComposition(compositionId: string)
async exportComposition(compositionId: string): Promise<string>
async importComposition(json: string)

See Also

Next Steps

  1. Practice: Create a simple composition
  2. Explore: Try connecting different flow types
  3. Learn: Study example compositions
  4. Build: Create your own complex systems
  5. Share: Export and share your compositions

Remember: The Flow Composer is all about visual thinking. Don't be afraid to experiment and iterate!