Skip to content

Architecture

PulseRoute is a 3-tier payment routing engine. Each tier adds intelligence on top of the previous one, and all three can be enabled or disabled at runtime.

System Overview

┌─────────────────────────────────────────────────────────────┐
│                      Your Payment Service                    │
│                                                              │
│   ┌──────────┐     ┌──────────┐     ┌──────────────────┐   │
│   │ SDK      │────>│ PulseRoute│────>│ Payment Processor │   │
│   │ Client   │<────│ API       │     │ (Stripe, Adyen..) │   │
│   └──────────┘     └──────────┘     └──────────────────┘   │
│        │                │                                    │
│        │ report_outcome │ evaluate_all()                     │
│        └────────────────┘                                    │
└─────────────────────────────────────────────────────────────┘

Pre-transaction: Your service calls POST /v1/route (or sdk.getRoute()) to get a routing decision. PulseRoute returns which processor to use and a traffic weight.

Post-transaction: Your service calls POST /v1/outcome (or sdk.reportOutcome()) with the result. PulseRoute uses this data to continuously improve routing decisions.

Tier 1: Sentinel (Health-Based Failover)

The foundation. Monitors processor health in real-time using transaction outcomes.

What it does:

  • Tracks success rates, error rates, and latency percentiles for each processor
  • Detects when a processor becomes degraded or unhealthy
  • Automatically fails over traffic to a healthy backup processor
  • Detects recovery and gradually shifts traffic back

Result: When your primary processor starts failing, PulseRoute detects it in seconds and routes traffic to your backup — before customers are significantly impacted.

Tier 2: Foresight (Predictive Failover)

Adds predictive capabilities using machine learning. Instead of reacting to failures, Tier 2 anticipates them.

What it does:

  • Analyzes patterns in processor health metrics over time
  • Produces a failure probability score for each processor
  • Triggers pre-emptive routing changes when failure risk is high
  • Feeds predictions into Tier 3 for smarter optimization

Result: PulseRoute starts shifting traffic away from a processor 30-60 seconds before it fails, preventing dropped transactions entirely.

Tier 3: Autopilot (Adaptive Optimization)

Replaces binary failover with continuous traffic optimization. Instead of "all primary" or "all secondary," Tier 3 dynamically allocates traffic across processors based on real-time performance.

What it does:

  • Continuously learns from transaction outcomes
  • Optimizes traffic allocation to maximize overall success rates
  • Incorporates Tier 2 failure predictions into routing decisions
  • Adapts to changing processor performance automatically

Result: PulseRoute finds the optimal traffic split across your processors and continuously adjusts it — even when no processor is "failing," it routes more traffic to whichever processor is performing best.

How the Tiers Work Together

Transaction outcome reported
        │
        ▼
  ┌─────────────┐
  │  Tier 1      │  Is the processor healthy?
  │  Sentinel    │  Success rate, latency, error patterns
  └──────┬───────┘
         │
         ▼
  ┌─────────────┐
  │  Tier 2      │  Will it stay healthy?
  │  Foresight   │  Failure probability prediction
  └──────┬───────┘
         │
         ▼
  ┌─────────────┐
  │  Tier 3      │  What's the optimal traffic split?
  │  Autopilot   │  Adaptive weight allocation
  └──────┬───────┘
         │
         ▼
  Routing Decision
  (processor + weight)

Each tier builds on the previous one. You can start with Tier 1 and enable higher tiers as you gain confidence.

Routing Rules

PulseRoute uses a rule-based system to match transactions to processor pairs. Rules are defined by transaction attributes:

  • Country — where the transaction originates (US, GB, etc.)
  • Currency — the payment currency (USD, EUR, etc.)
  • Payment method — card, wallet, bank transfer, etc.

You can define rules as specific as "US + USD + Visa → Stripe primary, Adyen backup" or as broad as "all transactions → Stripe primary, Adyen backup." More specific rules take priority over general ones.

The onboarding wizard or POST /v1/onboard endpoint auto-generates rules from your processor capabilities.

Multi-Tenancy

PulseRoute supports multi-tenant deployments with full data isolation between tenants. Each tenant has completely separate routing rules, health metrics, predictions, and webhooks. Tenants share the same PulseRoute deployment for operational simplicity.

See Deployment for configuration details.

Runtime Configuration

Tiers can be toggled at runtime without restart:

# Disable prediction (drop to Tier 1)
curl -X POST /v1/config/tiers -d '{"prediction_enabled": false}'

# Disable bandit (drop to Tier 2)
curl -X POST /v1/config/tiers -d '{"bandit_enabled": false}'

# Check current tier
curl /v1/config/tiers

Shadow Mode

Before going live, run PulseRoute in shadow mode. In this mode, PulseRoute observes your traffic and computes routing decisions, but doesn't change how your system actually routes payments.

After running in shadow mode, check the comparison report:

curl /v1/shadow-report?average_order_value=75

The report shows: - How many transactions PulseRoute would have routed differently - How many failures it would have prevented - Estimated revenue impact based on your average order value

This gives you concrete data on PulseRoute's value before you flip the switch.