Skip to content

Getting Started

Get PulseRoute running in 5 minutes.

Prerequisites

  • Docker and Docker Compose
  • curl (for testing)

1. Start the Stack

git clone <your-repo-url> pulseroute
cd pulseroute

# Start API + Redis
docker compose up -d

# Verify it's running
curl http://localhost:8080/
# {"service": "pulseroute", "version": "0.1.0"}

This starts:

Service Port Description
Redis 6379 Data store
API 8080 PulseRoute engine
Dashboard 8000 React monitoring UI

2. Add Routing Rules

Define how transactions should be routed. Each rule maps a set of transaction attributes to a primary and secondary (fallback) processor.

# US card payments: Stripe primary, Adyen fallback
curl -X POST http://localhost:8080/v1/rules \
  -H "Content-Type: application/json" \
  -d '{
    "rule_id": "us_cards",
    "attributes": ["US", "USD", "card", "*", "*", "*"],
    "primary_id": "stripe",
    "primary_name": "Stripe",
    "secondary_id": "adyen",
    "secondary_name": "Adyen"
  }'

# UK payments: Worldpay primary, Checkout.com fallback
curl -X POST http://localhost:8080/v1/rules \
  -H "Content-Type: application/json" \
  -d '{
    "rule_id": "uk_all",
    "attributes": ["GB", "GBP", "*"],
    "primary_id": "worldpay",
    "primary_name": "Worldpay",
    "secondary_id": "checkout",
    "secondary_name": "Checkout.com"
  }'

Attribute hierarchy

Rules match by transaction attributes (country, currency, payment method, etc.). Shorter lists are padded with * (wildcard). See Architecture for details.

3. Get Routing Decisions

Before processing a payment, ask PulseRoute where to send it:

curl -X POST http://localhost:8080/v1/route \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "currency": "USD",
    "payment_method": "card",
    "card_type": "visa",
    "amount": 99.99
  }'

Response: 

{
  "processor_id": "stripe",
  "weight": 0.9,
  "fallback_processor_id": "adyen",
  "decision_source": "rules",
  "failure_probability": null
}

4. Report Outcomes

After the payment completes, report the result so PulseRoute can learn:

curl -X POST http://localhost:8080/v1/outcome \
  -H "Content-Type: application/json" \
  -d '{
    "rule_id": "us_cards",
    "processor_id": "stripe",
    "success": true,
    "latency_ms": 120.0
  }'

5. Monitor Health

# Overall health
curl http://localhost:8080/v1/health

# Engine stats
curl http://localhost:8080/v1/stats

# Failover event log
curl http://localhost:8080/v1/failover-events

6. Watch Failover in Action

Simulate a processor outage by reporting failures:

# Report 20 failures for Stripe
for i in $(seq 1 20); do
  curl -s -X POST http://localhost:8080/v1/outcome \
    -H "Content-Type: application/json" \
    -d '{
      "rule_id": "us_cards",
      "processor_id": "stripe",
      "success": false,
      "latency_ms": 500.0
    }'
done

# Wait for evaluation cycle (5 seconds)
sleep 6

# Check routing — should now prefer Adyen
curl -X POST http://localhost:8080/v1/route \
  -H "Content-Type: application/json" \
  -d '{"country": "US", "currency": "USD", "payment_method": "card"}'

Optional: Enable Monitoring

Start Prometheus + Grafana for real-time dashboards:

docker compose --profile monitoring up -d

Next Steps