Routing Engine

Symphonies

A Symphony is a multi-stage workflow that orchestrates business logic across multiple steps. Each symphony defines:

• Stages - Ordered sequence of execution steps
• Recipes - Business logic to execute at each stage
• Conditions - Optional criteria for stage execution
• Requirements - Whether a stage is required or optional

Symphony: "Payment Processing"
├─ Stage 1: Compliance Check (required)
│  └─ Recipe: KYC Verification
├─ Stage 2: Risk Assessment (required)
│  └─ Recipe: Fraud Detection
├─ Stage 3: Payment Routing (required)
│  └─ Recipe: Provider Selection
└─ Stage 4: Notification (optional)
   └─ Recipe: Customer Alert

Stages & Recipes

Stages are sequential execution steps within a symphony:

• •Execute in order (Stage 1, then Stage 2, etc.)
• •Reference a specific Recipe to execute
• •Can be marked as required (failure stops execution) or optional
• •Can have a run condition to skip based on context

Recipes are templates for business logic:

• •Define which solutions to execute
• •Specify rules and decision criteria
• •Reusable across multiple symphonies and stages
• •Support versioning for gradual rollouts

Context Flow

The Context is the data that flows through your symphony execution:

{
  "amount": 1000,
  "currency": "USD",
  "customerId": "cust_123"
}

{
  "amount": 1000,
  "currency": "USD",
  "customerId": "cust_123",
  "stages": {
    "compliance": {
      "status": "approved",
      "riskLevel": "low"
    }
  }
}

{
  "amount": 1000,
  "currency": "USD",
  "customerId": "cust_123",
  "stages": {
    "compliance": {
      "status": "approved",
      "riskLevel": "low"
    },
    "routing": {
      "provider": "stripe",
      "fee": 29
    }
  }
}

When to Use Symphonies

• Multi-step workflows - Sequential execution with context sharing
• Conditional logic - Stages that skip based on previous results
• Complex orchestration - Coordinating multiple systems or decisions
• Reusable patterns - Standardising workflows across your organisation

Performance Optimization

• Minimise context size - Only include necessary data in initial context
• Use test mode - Test symphonies without affecting production systems
• Monitor execution times - Review stage timings to identify bottlenecks
• Cache when possible - Use subscriptions to avoid repeated lookups

Error Handling

• Mark critical stages as required - Ensure execution stops on critical failures
• Use optional stages for non-critical ops - Continue execution even if they fail
• Implement client-side retry logic - Engine does not auto-retry failed executions
• Monitor error patterns - Track error codes to identify systemic issues

Testing Strategies

• Use test mode - Set testMode: true in metadata to test without side effects
• Version pinning - Pin to specific versions during testing, auto-upgrade in production
• Mock external actions - Use overrides to replace external calls during testing
• Review execution history - Analyse historical executions to understand behaviour