Examples Overview

Working examples to learn saga patterns and best practices.

Example Applications

Example	Description	Stack
Order Saga	E-commerce order processing	RabbitMQ, PostgreSQL
Loan Application	Complex 30+ state workflow	RabbitMQ, PostgreSQL
Common Patterns	Reusable saga patterns	Various

Running Examples

Prerequisites

• Node.js 20+
• pnpm 9+
• Docker and Docker Compose

Quick Start

# Clone the repo
git clone https://github.com/d-e-a-n-f/saga-bus.git
cd saga-bus

# Install dependencies
pnpm install

# Start infrastructure (RabbitMQ, PostgreSQL)
docker compose up -d

# Run database migrations
pnpm --filter @saga-bus/store-postgres db:migrate

# Run the worker
pnpm --filter example-worker dev

# In another terminal, run the API
pnpm --filter example-nextjs dev

Access Points

Service	URL
Next.js App	http://localhost:3000
Worker Health	http://localhost:3001/health
RabbitMQ Management	http://localhost:15672 (guest/guest)
PostgreSQL	localhost:5432

Example Architecture

Press enter or space to select a node.You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Order Saga Flow

A simple e-commerce workflow demonstrating basic saga concepts:

Press enter or space to select a node.You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Key Concepts:

• Sequential state transitions
• Compensation on failure
• Message correlation

See Order Saga for the full implementation.

Loan Application Flow

A complex financial workflow with advanced patterns:

Press enter or space to select a node.You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Key Concepts:

• 30+ state transitions
• Parallel verification steps
• Conditional branching
• Timeout handling
• Document collection

See Loan Application for the full implementation.

Common Patterns

Reusable patterns applicable across many domains:

• Compensation - Rolling back distributed transactions
• Parallel Steps - Executing multiple operations concurrently
• Timeout Handling - Dealing with missing or delayed events
• State Machines - Modeling complex state transitions
• Idempotency - Safe message reprocessing

See Common Patterns for implementations.

Project Structure

saga-bus/
├── packages/
│   ├── core/              # Saga engine
│   ├── transport-rabbitmq/ # RabbitMQ transport
│   └── store-postgres/     # PostgreSQL store
├── apps/
│   ├── example-worker/     # Saga processor
│   ├── example-nextjs/     # API and UI
│   └── example-nestjs/     # NestJS API
└── docker-compose.yml      # Infrastructure

Environment Variables

# .env.local
DATABASE_URL=postgres://postgres:password@localhost:5432/sagabus
RABBITMQ_URL=amqp://guest:guest@localhost:5672
LOG_LEVEL=debug

Troubleshooting

RabbitMQ Connection Failed

# Check if RabbitMQ is running
docker compose ps

# View logs
docker compose logs rabbitmq

# Restart
docker compose restart rabbitmq

Database Connection Error

# Check if PostgreSQL is running
docker compose ps

# Run migrations
pnpm --filter @saga-bus/store-postgres db:migrate

# Reset database
pnpm --filter @saga-bus/store-postgres db:reset

Worker Not Processing Messages

1. Check worker logs for errors
2. Verify RabbitMQ connection
3. Check queue bindings in RabbitMQ Management UI
4. Ensure sagas are registered correctly

Next Steps

1. Order Saga - Start with the simple example
2. Loan Application - Explore advanced patterns
3. Common Patterns - Learn reusable techniques