System Design (HLD)Publish-Subscribe

Publish-Subscribe Pattern

LevelIntermediate

Duration75 mins

TopicPublish-Subscribe

3 / 5

Fan-Out Patterns

The Art of Event Distribution

When a user completes a purchase on an e-commerce platform, the ripple effect is enormous. The order needs to trigger inventory reservation, payment processing, shipping preparation, loyalty points calculation, recommendation engine updates, analytics event capture, email confirmation, push notification, fraud detection analysis, and potentially dozens more downstream actions.

This is fan-out in action—a single event spawning parallel processing across many independent systems. But not all fan-out is created equal. The pattern you choose affects system reliability, development velocity, operational complexity, and cost.

This page explores the major fan-out patterns, their trade-offs, and how to choose the right approach for different scenarios.

What You Will Learn

By the end of this page, you will understand simple fan-out, hierarchical fan-out, scatter-gather patterns, parallel processing strategies, and the trade-offs between synchronous and asynchronous fan-out approaches.

Simple Fan-Out: One Topic, Many Subscribers

The most straightforward fan-out pattern: publish an event to a single topic, and multiple independent subscriptions each receive the event. This is the native behavior of pub-sub systems.

Converting Mermaid diagram...

Simple Fan-Out Characteristics

•Decentralized processing: Each consumer operates independently; no coordination required
•Heterogeneous consumers: Different processing speeds, different technologies, different SLAs—all acceptable
•Additive scaling: Adding new consumers requires no changes to producer or existing consumers
•Fault isolation: One consumer's failure doesn't affect others
•Independent retries: Each subscription has its own acknowledgment and retry policy

When to Use Simple Fan-Out:

All consumers need the complete, unmodified event
Consumers are truly independent (no coordination needed between them)
Different consumers have different processing requirements (speed, reliability, ordering)
You want maximum decoupling between producer and consumers

Limitations:

Each consumer receives ALL events, even if only some are relevant (addressed by filtering)
No built-in mechanism for aggregating results from multiple consumers (that's scatter-gather)
Large events multiply network traffic (one copy per subscriber)

simple-fanout-example.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// Simple fan-out: One publish, many independent consumers
 
// Producer: Order Service (knows nothing about consumers)
async function publishOrderCompleted(order: Order): Promise<void> {
  const event: OrderCompletedEvent = {
    eventId: generateId(),
    eventType: 'ORDER_COMPLETED',
    timestamp: new Date().toISOString(),
    payload: {
      orderId: order.id,
      customerId: order.customerId,
      items: order.items,
      totalAmount: order.totalAmount,
      shippingAddress: order.shippingAddress,
    },
  };
  
  // Single publish - broker handles fan-out to all subscribers
  await pubsub.topic('orders.completed').publish(event);
}
 
// Consumer 1: Inventory Service
async function inventoryConsumer(message: Message): Promise<void> {
  const event = parse<OrderCompletedEvent>(message);
  for (const item of event.payload.items) {
    await inventoryService.reserveStock(item.sku, item.quantity);
  }
  await message.ack();
}
 
// Consumer 2: Email Service (completely independent)
async function emailConsumer(message: Message): Promise<void> {
  const event = parse<OrderCompletedEvent>(message);
  await emailService.sendOrderConfirmation({
    to: event.payload.customerId,
    orderId: event.payload.orderId,
    items: event.payload.items,
    total: event.payload.totalAmount,
  });
  await message.ack();
}
 
// Consumer 3: Analytics Pipeline (different processing characteristics)
async function analyticsConsumer(messages: Message[]): Promise<void> {
  // Batch processing - analytics can handle higher latency
  const events = messages.map(m => parse<OrderCompletedEvent>(m));
  await analyticsService.ingestOrderEvents(events);
  await Promise.all(messages.map(m => m.ack()));
}

Hierarchical Fan-Out

When fan-out becomes too broad at a single level, or when different event types need different distribution paths, hierarchical fan-out introduces intermediate topics that re-broadcast events to downstream subscribers.

Converting Mermaid diagram...

Why Hierarchical Fan-Out?

As systems grow, simple fan-out faces challenges:

Topic pollution: A single topic with 50 subscribers becomes hard to manage and reason about
Coupling creep: Producers start adding fields because 'subscriber X needs it', polluting the event for everyone
Performance concerns: Very high subscriber counts can strain broker fan-out capacity
Lifecycle mismatch: Different domains evolve at different speeds

Hierarchical fan-out introduces event routers (sometimes called event bridges) that:

Subscribe to origin events
Transform, enrich, or filter events for their domain
Republish to domain-specific topics
Let domain consumers subscribe to relevant topics only

Router Responsibilities

•Event translation: Convert origin event schema to domain-specific schema
•Enrichment: Add domain-relevant context (lookup customer tier, add region info)
•Filtering: Only republish events relevant to this domain
•Aggregation: Combine multiple origin events into single domain event
•Protocol bridging: Translate between different messaging systems or formats

hierarchical-fanout-router.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// Event Router: Translates origin events to domain events
 
// Origin event (from Order Service)
interface OrderCompletedEvent {
  orderId: string;
  customerId: string;
  items: OrderItem[];
  totalAmount: number;
  shippingAddress: Address;
}
 
// Domain event (for Fulfillment domain)
interface FulfillmentRequiredEvent {
  fulfillmentId: string;
  orderId: string;
  warehouse: string;        // Enriched: determined by address
  priority: 'standard' | 'express';
  items: FulfillmentItem[]; // Transformed: includes warehouse location
  shipBy: string;           // Derived: based on shipping method
}
 
// Router: Order Events → Fulfillment Domain
class FulfillmentEventRouter {
  async handleOrderCompleted(event: OrderCompletedEvent): Promise<void> {
    // 1. Filter: Only orders with physical goods need fulfillment
    if (!this.hasPhysicalItems(event.items)) {
      return; // Digital-only orders skip fulfillment
    }
    
    // 2. Enrich: Determine optimal warehouse
    const warehouse = await this.warehouseService.findOptimalWarehouse(
      event.items,
      event.shippingAddress
    );
    
    // 3. Transform: Convert to domain event
    const fulfillmentEvent: FulfillmentRequiredEvent = {
      fulfillmentId: generateId(),
      orderId: event.orderId,
      warehouse: warehouse.id,
      priority: this.determinePriority(event),
      items: await this.enrichItemsWithWarehouseLocations(event.items, warehouse),
      shipBy: this.calculateShipDeadline(event),
    };
    
    // 4. Republish to domain topic
    await this.broker.publish('fulfillment.required', fulfillmentEvent);
  }
}

Router as Single Point of Failure

Event routers introduce an extra hop and potential failure point. Ensure routers are highly available, idempotent (can replay origin events safely), and monitored. If the router fails, downstream consumers see no events. Consider router replicas with consumer-group semantics for horizontal scaling.

Filtered Fan-Out: Server-Side Message Selection

When consumers only need a subset of events from a topic, filtered fan-out applies selection criteria at the broker level, delivering only matching messages to each subscription.

The Problem with Client-Side Filtering:

Without broker-side filtering, consumers receive all events and discard unwanted ones:

Topic: payment-events (10,000 events/sec)
├─ Subscription A (wants PAYMENT_COMPLETED events) → receives 10,000/sec, uses 2,000/sec, discards 8,000/sec
├─ Subscription B (wants PAYMENT_FAILED events) → receives 10,000/sec, uses 500/sec, discards 9,500/sec
└─ Subscription C (wants high-value events >$1000) → receives 10,000/sec, uses 100/sec, discards 9,900/sec

This wastes network bandwidth, consumer CPU, and acknowledgment overhead.

With Broker-Side Filtering:

Topic: payment-events (10,000 events/sec)
├─ Subscription A (filter: eventType = 'PAYMENT_COMPLETED') → receives 2,000/sec
├─ Subscription B (filter: eventType = 'PAYMENT_FAILED') → receives 500/sec  
└─ Subscription C (filter: amount > 1000) → receives 100/sec

The broker evaluates filter expressions before delivery, dramatically reducing unnecessary traffic.

Filter Capabilities by Platform
Platform	Filter Type	Example	Notes
Google Pub/Sub	Attribute-based	attributes.eventType = 'COMPLETED'	Filters on message attributes; no payload filtering
AWS SNS	Message filtering	{ 'eventType': ['COMPLETED', 'FAILED'] }	JSON-based filter on message attributes
RabbitMQ	Routing keys + topic exchange	payments.completed.* vs payments.failed.*	Uses hierarchical routing key matching
Apache Kafka	No native filtering	N/A	Consumers filter; use Kafka Streams for pre-filtering to new topics
Azure Event Grid	Advanced filters	Subject begins with /payments/high-value	Rich filter expressions on properties

filtered-subscription-example.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// Example: Google Pub/Sub with subscription filters
 
// Publisher: Add filterable attributes to messages
async function publishPaymentEvent(event: PaymentEvent): Promise<void> {
  await pubsub.topic('payment-events').publishMessage({
    data: Buffer.from(JSON.stringify(event)),
    attributes: {
      // Attributes are used for filtering (not the payload)
      eventType: event.type,          // 'COMPLETED', 'FAILED', 'REFUNDED'
      region: event.merchantRegion,   // 'US', 'EU', 'APAC'
      amountTier: event.amount > 1000 ? 'high' : 'standard',
      currency: event.currency,
    },
  });
}
 
// Subscription 1: Only high-value completed payments
const highValueCompletedSub = await pubsub
  .topic('payment-events')
  .createSubscription('high-value-completed-sub', {
    filter: 'attributes.eventType = "COMPLETED" AND attributes.amountTier = "high"',
  });
 
// Subscription 2: Only failed payments in EU region
const euFailedSub = await pubsub
  .topic('payment-events')
  .createSubscription('eu-failed-payments-sub', {
    filter: 'attributes.eventType = "FAILED" AND attributes.region = "EU"',
  });
 
// Subscription 3: All refunds (no additional filtering)
const refundsSub = await pubsub
  .topic('payment-events')
  .createSubscription('all-refunds-sub', {
    filter: 'attributes.eventType = "REFUNDED"',
  });

Filter Design Considerations

Design filterable attributes upfront—changing them requires publisher changes and subscriber migrations. Use coarse-grained categories (status, region, priority) rather than fine-grained values. Remember that filter evaluation has a cost; extremely complex filters may not outperform client-side filtering.

Scatter-Gather Pattern

While pure pub-sub is fire-and-forget (producer doesn't wait for consumers), the scatter-gather pattern overlays request-response semantics: scatter a request to multiple services, then gather their responses to form a composite result.

Converting Mermaid diagram...

How It Works:

Scatter: Orchestrator publishes request to multiple services (or invokes APIs in parallel)
Parallel Processing: Each service processes independently
Gather: Orchestrator collects responses with timeout
Aggregate: Combine responses into unified result
Handle Partial Failure: Proceed with available responses if some services fail

Scatter-Gather in Messaging:

The pattern can be implemented with pub-sub by:

Publishing request with correlation ID to multiple topics or services
Services publish responses to a response topic, tagged with correlation ID
Orchestrator subscribes to response topic, aggregates by correlation ID

scatter-gather-implementation.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
// Scatter-Gather with async messaging
 
interface ScatterRequest {
  correlationId: string;
  requestType: string;
  payload: unknown;
  replyTo: string; // Topic for responses
  timeout: number;
}
 
interface GatherResponse {
  correlationId: string;
  source: string;
  payload: unknown;
  success: boolean;
  error?: string;
}
 
class ScatterGatherOrchestrator {
  private pendingRequests = new Map<string, {
    resolve: (responses: GatherResponse[]) => void;
    responses: GatherResponse[];
    expectedCount: number;
    timer: NodeJS.Timeout;
  }>();
 
  async scatterGather(
    request: { type: string; payload: unknown },
    targets: string[],
    timeoutMs: number = 5000
  ): Promise<GatherResponse[]> {
    const correlationId = generateCorrelationId();
    
    return new Promise(async (resolve) => {
      // Set up response collection
      this.pendingRequests.set(correlationId, {
        resolve,
        responses: [],
        expectedCount: targets.length,
        timer: setTimeout(() => this.handleTimeout(correlationId), timeoutMs),
      });
      
      // Scatter: Publish to all targets in parallel
      await Promise.all(targets.map(target =>
        this.broker.publish(`requests.${target}`, {
          correlationId,
          requestType: request.type,
          payload: request.payload,
          replyTo: 'responses.orchestrator',
          timeout: timeoutMs,
        })
      ));
    });
  }
 
  async handleResponse(message: Message): Promise<void> {
    const response: GatherResponse = JSON.parse(message.data);
    const pending = this.pendingRequests.get(response.correlationId);
    
    if (!pending) {
      // Late response (already timed out) - discard
      return message.ack();
    }
    
    // Gather: Collect response
    pending.responses.push(response);
    
    // Check if complete
    if (pending.responses.length >= pending.expectedCount) {
      clearTimeout(pending.timer);
      this.pendingRequests.delete(response.correlationId);
      pending.resolve(pending.responses);
    }
    
    await message.ack();
  }
 
  private handleTimeout(correlationId: string): void {
    const pending = this.pendingRequests.get(correlationId);
    if (pending) {
      this.pendingRequests.delete(correlationId);
      // Resolve with partial responses
      pending.resolve(pending.responses);
    }
  }
}

When to Use Scatter-Gather

Use scatter-gather when you need results from multiple services to compose a response (product pages, search aggregation, multi-source pricing). For fire-and-forget fan-out where you don't need responses, simple pub-sub is more appropriate and simpler to implement.

Event Sourcing Fan-Out

In event-sourced systems, the event log serves as both the source of truth and the fan-out mechanism. Every state change is captured as an immutable event, and multiple consumers project different views from the same event stream.

Converting Mermaid diagram...

Why This Matters:

Event sourcing fan-out differs from traditional pub-sub in crucial ways:

Replay capability: New projections can be added anytime and catch up by replaying from the beginning
Single source of truth: All projections derive from the same authoritative event stream
Temporal queries: Ask 'what was the balance on January 15?' by replaying to that point
Auditability: Complete history preserved; nothing lost

Implementation Considerations:

Event versioning: Events must be forward-compatible; old events need to be processable
Projection snapshots: For long event streams, periodically snapshot projection state to speed up rebuilds
Catch-up subscriptions: Handle both live events and historical replay
Exactly-once projections: Ensure projections are idempotent to handle replays safely

event-sourcing-projection.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
// Event Sourcing: Multiple projections from same event stream
 
type AccountEvent =
  | { type: 'ACCOUNT_OPENED'; accountId: string; customerId: string; openedAt: string }
  | { type: 'MONEY_DEPOSITED'; accountId: string; amount: number; timestamp: string }
  | { type: 'MONEY_WITHDRAWN'; accountId: string; amount: number; timestamp: string }
  | { type: 'ACCOUNT_CLOSED'; accountId: string; closedAt: string };
 
// Projection 1: Current Balance
class BalanceProjection {
  private balances = new Map<string, number>();
  
  apply(event: AccountEvent): void {
    switch (event.type) {
      case 'ACCOUNT_OPENED':
        this.balances.set(event.accountId, 0);
        break;
      case 'MONEY_DEPOSITED':
        this.balances.set(
          event.accountId,
          (this.balances.get(event.accountId) || 0) + event.amount
        );
        break;
      case 'MONEY_WITHDRAWN':
        this.balances.set(
          event.accountId,
          (this.balances.get(event.accountId) || 0) - event.amount
        );
        break;
      case 'ACCOUNT_CLOSED':
        this.balances.delete(event.accountId);
        break;
    }
  }
  
  getBalance(accountId: string): number {
    return this.balances.get(accountId) || 0;
  }
}
 
// Projection 2: Monthly Transaction Summary
class MonthlySummaryProjection {
  private summaries = new Map<string, { deposits: number; withdrawals: number; count: number }>();
  
  apply(event: AccountEvent): void {
    if (event.type === 'MONEY_DEPOSITED' || event.type === 'MONEY_WITHDRAWN') {
      const month = event.timestamp.substring(0, 7); // YYYY-MM
      const key = `${event.accountId}:${month}`;
      const current = this.summaries.get(key) || { deposits: 0, withdrawals: 0, count: 0 };
      
      if (event.type === 'MONEY_DEPOSITED') {
        current.deposits += event.amount;
      } else {
        current.withdrawals += event.amount;
      }
      current.count++;
      
      this.summaries.set(key, current);
    }
  }
}
 
// Consumer: Fan-out to all projections
async function consumeAccountEvents(): Promise<void> {
  const balanceProjection = new BalanceProjection();
  const summaryProjection = new MonthlySummaryProjection();
  // ... more projections
  
  // Subscribe from earliest for full rebuild, or from checkpoint for live
  await eventStream.subscribe('account-events', { startFrom: checkpoint }, async (event) => {
    // Fan-out to all projections (same event, multiple handlers)
    balanceProjection.apply(event);
    summaryProjection.apply(event);
    // ... more projections
    
    // Checkpoint for recovery
    await saveCheckpoint(event.position);
  });
}

Fan-Out at Scale: Performance Considerations

As subscriber count grows, fan-out performance becomes critical. Understanding the mechanics helps you design systems that scale efficiently.

Fan-Out Scaling Factors
Factor	Impact	Mitigation
Subscriber count	Linear increase in broker work per message	Hierarchical fan-out; separate topics by domain
Message size	Network bandwidth multiplied by subscribers	Reference pattern (URI instead of payload); compression
Subscriber speed variance	Slow subscribers don't block fast ones (good)	Ensure backpressure per subscription; monitor lag
Acknowledgment overhead	Per-subscription ack tracking	Batch acknowledgments; tune ack deadlines
Message ordering	Ordering constraints limit parallelism	Relax ordering where possible; partition by entity

The Reference Pattern for Large Payloads

When events contain large data (images, documents, batch records), fan-out multiplies bandwidth consumption. The reference pattern separates data storage from event routing:

Store large payload in object storage (S3, GCS, Azure Blob)
Publish event containing only a reference (URI) to the payload
Subscribers fetch payload on demand (with caching)

This keeps the message bus lean and fast, while large data flows directly from storage to consumer.

reference-pattern.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
// Reference Pattern: Large payload via object storage
 
interface LargeDocumentEvent {
  eventId: string;
  eventType: 'DOCUMENT_UPLOADED';
  timestamp: string;
  
  // Metadata (small, included in event)
  documentId: string;
  fileName: string;
  contentType: string;
  fileSizeBytes: number;
  uploadedBy: string;
  
  // Reference to large content (not included in event)
  contentRef: {
    bucket: string;
    key: string;
    region: string;
    presignedUrl?: string; // Optional: pre-signed URL with expiry
  };
}
 
// Publisher: Store content, publish reference
async function publishDocumentUploaded(
  document: Buffer,
  metadata: DocumentMetadata
): Promise<void> {
  // Step 1: Store large content in object storage
  const key = `documents/${metadata.documentId}/${metadata.fileName}`;
  await s3.putObject({
    Bucket: 'documents-bucket',
    Key: key,
    Body: document,
    ContentType: metadata.contentType,
  });
  
  // Step 2: Publish small event with reference
  const event: LargeDocumentEvent = {
    eventId: generateId(),
    eventType: 'DOCUMENT_UPLOADED',
    timestamp: new Date().toISOString(),
    documentId: metadata.documentId,
    fileName: metadata.fileName,
    contentType: metadata.contentType,
    fileSizeBytes: document.length,
    uploadedBy: metadata.userId,
    contentRef: {
      bucket: 'documents-bucket',
      key,
      region: 'us-east-1',
    },
  };
  
  // Event is small (~500 bytes) regardless of document size
  await pubsub.topic('documents.uploaded').publish(event);
}
 
// Consumer: Fetch content on demand
async function processDocumentEvent(event: LargeDocumentEvent): Promise<void> {
  // Only fetch if this consumer needs the content
  if (needsContent(event)) {
    const content = await s3.getObject({
      Bucket: event.contentRef.bucket,
      Key: event.contentRef.key,
    });
    await processContent(content.Body);
  } else {
    // Some consumers only need metadata
    await processMetadataOnly(event);
  }
}

Presigned URLs for Cross-Account Access

When consumers are in different accounts or networks, include a time-limited presigned URL in the event. This allows consumers to fetch content without needing storage credentials, while the URL expires (typically 15 minutes to 1 hour) to limit exposure.

Fan-Out Anti-Patterns

Certain patterns seem convenient but lead to fragile, hard-to-maintain systems. Recognizing these anti-patterns helps you avoid common pitfalls.

Anti-Patterns to Avoid

•God Topic: One topic for all events ('events', 'all-messages'). Every consumer receives everything; filtering is impossible; topic becomes a bottleneck and reasoning nightmare. Fix: Domain-specific topics with clear boundaries.
•Polluted Events: Adding fields to events because 'consumer X needs them'. Over time, events become kitchen sinks with fields for every consumer. Fix: Publish clean domain events; let consumers enrich as needed.
•Orchestrated Fan-Out: Producer explicitly publishes to multiple topics based on consumer needs. Producer becomes coupled to all consumers; adding consumers requires producer changes. Fix: Publish once; let subscriptions or routers handle distribution.
•Synchronous Disguised as Async: Producer waits for all consumers to process before continuing. Defeats the purpose of async; reintroduces coupling. Fix: True fire-and-forget; use scatter-gather only when aggregation is actually needed.
•Phantom Subscriptions: Subscriptions for consumers that no longer exist. Messages accumulate indefinitely, wasting resources. Fix: Subscription lifecycle management; monitor and alert on inactive subscriptions.

Anti-Pattern Detection
Symptom	Likely Anti-Pattern	Root Cause
Producer code changes when consumers change	Orchestrated fan-out	Producer knows about consumers
Events have many optional fields	Polluted events	Events designed for consumers, not domain
All consumers process all event types	God topic	Missing topic segmentation
High disk usage on broker	Phantom subscriptions	Stale subscriptions accumulating messages
Producer latency tied to consumer latency	Synchronous disguised as async	Producer waiting for processing

Summary: Fan-Out Patterns

We've explored the major patterns for distributing events to multiple consumers. Let's consolidate the key concepts:

Key Takeaways

•Simple fan-out is the baseline: One topic, many independent subscriptions, each receiving all events. Maximum decoupling, minimum coordination.
•Hierarchical fan-out manages complexity: Event routers translate and redistribute events to domain-specific topics, enabling cleaner boundaries.
•Filtered fan-out reduces waste: Broker-side filtering delivers only relevant events to each subscription, saving bandwidth and processing.
•Scatter-gather adds request-response: When you need aggregated results from multiple services, overlay scatter-gather on top of messaging.
•Event sourcing enables temporal fan-out: Multiple projections from one event stream, with replay capability for new views.
•Reference pattern scales large payloads: Store data in object storage, publish references in events to keep the message bus efficient.

What's Next:

Now that we understand how events flow to multiple consumers, we'll explore message filtering—the techniques for ensuring each consumer receives precisely the events it needs, without wasting resources on irrelevant messages.

Page Complete

You now understand the major fan-out patterns that enable one-to-many event distribution. From simple pub-sub to hierarchical routing to scatter-gather aggregation, these patterns form the architectural vocabulary for building scalable, event-driven systems.

3 / 5

Loading learning content...

System Design (HLD)Publish-Subscribe

Publish-Subscribe Pattern

LevelIntermediate

Duration75 mins

TopicPublish-Subscribe

3 / 5

Fan-Out Patterns

The Art of Event Distribution

This page explores the major fan-out patterns, their trade-offs, and how to choose the right approach for different scenarios.

What You Will Learn

Simple Fan-Out: One Topic, Many Subscribers

The most straightforward fan-out pattern: publish an event to a single topic, and multiple independent subscriptions each receive the event. This is the native behavior of pub-sub systems.

Converting Mermaid diagram...

Simple Fan-Out Characteristics

•Decentralized processing: Each consumer operates independently; no coordination required
•Heterogeneous consumers: Different processing speeds, different technologies, different SLAs—all acceptable
•Additive scaling: Adding new consumers requires no changes to producer or existing consumers
•Fault isolation: One consumer's failure doesn't affect others
•Independent retries: Each subscription has its own acknowledgment and retry policy

When to Use Simple Fan-Out:

All consumers need the complete, unmodified event
Consumers are truly independent (no coordination needed between them)
Different consumers have different processing requirements (speed, reliability, ordering)
You want maximum decoupling between producer and consumers

Limitations:

Each consumer receives ALL events, even if only some are relevant (addressed by filtering)
No built-in mechanism for aggregating results from multiple consumers (that's scatter-gather)
Large events multiply network traffic (one copy per subscriber)

simple-fanout-example.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// Simple fan-out: One publish, many independent consumers
 
// Producer: Order Service (knows nothing about consumers)
async function publishOrderCompleted(order: Order): Promise<void> {
  const event: OrderCompletedEvent = {
    eventId: generateId(),
    eventType: 'ORDER_COMPLETED',
    timestamp: new Date().toISOString(),
    payload: {
      orderId: order.id,
      customerId: order.customerId,
      items: order.items,
      totalAmount: order.totalAmount,
      shippingAddress: order.shippingAddress,
    },
  };
  
  // Single publish - broker handles fan-out to all subscribers
  await pubsub.topic('orders.completed').publish(event);
}
 
// Consumer 1: Inventory Service
async function inventoryConsumer(message: Message): Promise<void> {
  const event = parse<OrderCompletedEvent>(message);
  for (const item of event.payload.items) {
    await inventoryService.reserveStock(item.sku, item.quantity);
  }
  await message.ack();
}
 
// Consumer 2: Email Service (completely independent)
async function emailConsumer(message: Message): Promise<void> {
  const event = parse<OrderCompletedEvent>(message);
  await emailService.sendOrderConfirmation({
    to: event.payload.customerId,
    orderId: event.payload.orderId,
    items: event.payload.items,
    total: event.payload.totalAmount,
  });
  await message.ack();
}
 
// Consumer 3: Analytics Pipeline (different processing characteristics)
async function analyticsConsumer(messages: Message[]): Promise<void> {
  // Batch processing - analytics can handle higher latency
  const events = messages.map(m => parse<OrderCompletedEvent>(m));
  await analyticsService.ingestOrderEvents(events);
  await Promise.all(messages.map(m => m.ack()));
}

Hierarchical Fan-Out

Converting Mermaid diagram...

Why Hierarchical Fan-Out?

As systems grow, simple fan-out faces challenges:

Topic pollution: A single topic with 50 subscribers becomes hard to manage and reason about
Coupling creep: Producers start adding fields because 'subscriber X needs it', polluting the event for everyone
Performance concerns: Very high subscriber counts can strain broker fan-out capacity
Lifecycle mismatch: Different domains evolve at different speeds

Hierarchical fan-out introduces event routers (sometimes called event bridges) that:

Subscribe to origin events
Transform, enrich, or filter events for their domain
Republish to domain-specific topics
Let domain consumers subscribe to relevant topics only

Router Responsibilities

•Event translation: Convert origin event schema to domain-specific schema
•Enrichment: Add domain-relevant context (lookup customer tier, add region info)
•Filtering: Only republish events relevant to this domain
•Aggregation: Combine multiple origin events into single domain event
•Protocol bridging: Translate between different messaging systems or formats

hierarchical-fanout-router.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// Event Router: Translates origin events to domain events
 
// Origin event (from Order Service)
interface OrderCompletedEvent {
  orderId: string;
  customerId: string;
  items: OrderItem[];
  totalAmount: number;
  shippingAddress: Address;
}
 
// Domain event (for Fulfillment domain)
interface FulfillmentRequiredEvent {
  fulfillmentId: string;
  orderId: string;
  warehouse: string;        // Enriched: determined by address
  priority: 'standard' | 'express';
  items: FulfillmentItem[]; // Transformed: includes warehouse location
  shipBy: string;           // Derived: based on shipping method
}
 
// Router: Order Events → Fulfillment Domain
class FulfillmentEventRouter {
  async handleOrderCompleted(event: OrderCompletedEvent): Promise<void> {
    // 1. Filter: Only orders with physical goods need fulfillment
    if (!this.hasPhysicalItems(event.items)) {
      return; // Digital-only orders skip fulfillment
    }
    
    // 2. Enrich: Determine optimal warehouse
    const warehouse = await this.warehouseService.findOptimalWarehouse(
      event.items,
      event.shippingAddress
    );
    
    // 3. Transform: Convert to domain event
    const fulfillmentEvent: FulfillmentRequiredEvent = {
      fulfillmentId: generateId(),
      orderId: event.orderId,
      warehouse: warehouse.id,
      priority: this.determinePriority(event),
      items: await this.enrichItemsWithWarehouseLocations(event.items, warehouse),
      shipBy: this.calculateShipDeadline(event),
    };
    
    // 4. Republish to domain topic
    await this.broker.publish('fulfillment.required', fulfillmentEvent);
  }
}

Router as Single Point of Failure

Filtered Fan-Out: Server-Side Message Selection

When consumers only need a subset of events from a topic, filtered fan-out applies selection criteria at the broker level, delivering only matching messages to each subscription.

The Problem with Client-Side Filtering:

Without broker-side filtering, consumers receive all events and discard unwanted ones:

Topic: payment-events (10,000 events/sec)
├─ Subscription A (wants PAYMENT_COMPLETED events) → receives 10,000/sec, uses 2,000/sec, discards 8,000/sec
├─ Subscription B (wants PAYMENT_FAILED events) → receives 10,000/sec, uses 500/sec, discards 9,500/sec
└─ Subscription C (wants high-value events >$1000) → receives 10,000/sec, uses 100/sec, discards 9,900/sec

This wastes network bandwidth, consumer CPU, and acknowledgment overhead.

With Broker-Side Filtering:

Topic: payment-events (10,000 events/sec)
├─ Subscription A (filter: eventType = 'PAYMENT_COMPLETED') → receives 2,000/sec
├─ Subscription B (filter: eventType = 'PAYMENT_FAILED') → receives 500/sec  
└─ Subscription C (filter: amount > 1000) → receives 100/sec

The broker evaluates filter expressions before delivery, dramatically reducing unnecessary traffic.

Filter Capabilities by Platform
Platform	Filter Type	Example	Notes
Google Pub/Sub	Attribute-based	attributes.eventType = 'COMPLETED'	Filters on message attributes; no payload filtering
AWS SNS	Message filtering	{ 'eventType': ['COMPLETED', 'FAILED'] }	JSON-based filter on message attributes
RabbitMQ	Routing keys + topic exchange	payments.completed.* vs payments.failed.*	Uses hierarchical routing key matching
Apache Kafka	No native filtering	N/A	Consumers filter; use Kafka Streams for pre-filtering to new topics
Azure Event Grid	Advanced filters	Subject begins with /payments/high-value	Rich filter expressions on properties

filtered-subscription-example.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// Example: Google Pub/Sub with subscription filters
 
// Publisher: Add filterable attributes to messages
async function publishPaymentEvent(event: PaymentEvent): Promise<void> {
  await pubsub.topic('payment-events').publishMessage({
    data: Buffer.from(JSON.stringify(event)),
    attributes: {
      // Attributes are used for filtering (not the payload)
      eventType: event.type,          // 'COMPLETED', 'FAILED', 'REFUNDED'
      region: event.merchantRegion,   // 'US', 'EU', 'APAC'
      amountTier: event.amount > 1000 ? 'high' : 'standard',
      currency: event.currency,
    },
  });
}
 
// Subscription 1: Only high-value completed payments
const highValueCompletedSub = await pubsub
  .topic('payment-events')
  .createSubscription('high-value-completed-sub', {
    filter: 'attributes.eventType = "COMPLETED" AND attributes.amountTier = "high"',
  });
 
// Subscription 2: Only failed payments in EU region
const euFailedSub = await pubsub
  .topic('payment-events')
  .createSubscription('eu-failed-payments-sub', {
    filter: 'attributes.eventType = "FAILED" AND attributes.region = "EU"',
  });
 
// Subscription 3: All refunds (no additional filtering)
const refundsSub = await pubsub
  .topic('payment-events')
  .createSubscription('all-refunds-sub', {
    filter: 'attributes.eventType = "REFUNDED"',
  });

Filter Design Considerations

Scatter-Gather Pattern

Converting Mermaid diagram...

How It Works:

Scatter: Orchestrator publishes request to multiple services (or invokes APIs in parallel)
Parallel Processing: Each service processes independently
Gather: Orchestrator collects responses with timeout
Aggregate: Combine responses into unified result
Handle Partial Failure: Proceed with available responses if some services fail

Scatter-Gather in Messaging:

The pattern can be implemented with pub-sub by:

Publishing request with correlation ID to multiple topics or services
Services publish responses to a response topic, tagged with correlation ID
Orchestrator subscribes to response topic, aggregates by correlation ID

scatter-gather-implementation.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
// Scatter-Gather with async messaging
 
interface ScatterRequest {
  correlationId: string;
  requestType: string;
  payload: unknown;
  replyTo: string; // Topic for responses
  timeout: number;
}
 
interface GatherResponse {
  correlationId: string;
  source: string;
  payload: unknown;
  success: boolean;
  error?: string;
}
 
class ScatterGatherOrchestrator {
  private pendingRequests = new Map<string, {
    resolve: (responses: GatherResponse[]) => void;
    responses: GatherResponse[];
    expectedCount: number;
    timer: NodeJS.Timeout;
  }>();
 
  async scatterGather(
    request: { type: string; payload: unknown },
    targets: string[],
    timeoutMs: number = 5000
  ): Promise<GatherResponse[]> {
    const correlationId = generateCorrelationId();
    
    return new Promise(async (resolve) => {
      // Set up response collection
      this.pendingRequests.set(correlationId, {
        resolve,
        responses: [],
        expectedCount: targets.length,
        timer: setTimeout(() => this.handleTimeout(correlationId), timeoutMs),
      });
      
      // Scatter: Publish to all targets in parallel
      await Promise.all(targets.map(target =>
        this.broker.publish(`requests.${target}`, {
          correlationId,
          requestType: request.type,
          payload: request.payload,
          replyTo: 'responses.orchestrator',
          timeout: timeoutMs,
        })
      ));
    });
  }
 
  async handleResponse(message: Message): Promise<void> {
    const response: GatherResponse = JSON.parse(message.data);
    const pending = this.pendingRequests.get(response.correlationId);
    
    if (!pending) {
      // Late response (already timed out) - discard
      return message.ack();
    }
    
    // Gather: Collect response
    pending.responses.push(response);
    
    // Check if complete
    if (pending.responses.length >= pending.expectedCount) {
      clearTimeout(pending.timer);
      this.pendingRequests.delete(response.correlationId);
      pending.resolve(pending.responses);
    }
    
    await message.ack();
  }
 
  private handleTimeout(correlationId: string): void {
    const pending = this.pendingRequests.get(correlationId);
    if (pending) {
      this.pendingRequests.delete(correlationId);
      // Resolve with partial responses
      pending.resolve(pending.responses);
    }
  }
}

When to Use Scatter-Gather

Event Sourcing Fan-Out

Converting Mermaid diagram...

Why This Matters:

Event sourcing fan-out differs from traditional pub-sub in crucial ways:

Replay capability: New projections can be added anytime and catch up by replaying from the beginning
Single source of truth: All projections derive from the same authoritative event stream
Temporal queries: Ask 'what was the balance on January 15?' by replaying to that point
Auditability: Complete history preserved; nothing lost

Implementation Considerations:

Event versioning: Events must be forward-compatible; old events need to be processable
Projection snapshots: For long event streams, periodically snapshot projection state to speed up rebuilds
Catch-up subscriptions: Handle both live events and historical replay
Exactly-once projections: Ensure projections are idempotent to handle replays safely

event-sourcing-projection.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
// Event Sourcing: Multiple projections from same event stream
 
type AccountEvent =
  | { type: 'ACCOUNT_OPENED'; accountId: string; customerId: string; openedAt: string }
  | { type: 'MONEY_DEPOSITED'; accountId: string; amount: number; timestamp: string }
  | { type: 'MONEY_WITHDRAWN'; accountId: string; amount: number; timestamp: string }
  | { type: 'ACCOUNT_CLOSED'; accountId: string; closedAt: string };
 
// Projection 1: Current Balance
class BalanceProjection {
  private balances = new Map<string, number>();
  
  apply(event: AccountEvent): void {
    switch (event.type) {
      case 'ACCOUNT_OPENED':
        this.balances.set(event.accountId, 0);
        break;
      case 'MONEY_DEPOSITED':
        this.balances.set(
          event.accountId,
          (this.balances.get(event.accountId) || 0) + event.amount
        );
        break;
      case 'MONEY_WITHDRAWN':
        this.balances.set(
          event.accountId,
          (this.balances.get(event.accountId) || 0) - event.amount
        );
        break;
      case 'ACCOUNT_CLOSED':
        this.balances.delete(event.accountId);
        break;
    }
  }
  
  getBalance(accountId: string): number {
    return this.balances.get(accountId) || 0;
  }
}
 
// Projection 2: Monthly Transaction Summary
class MonthlySummaryProjection {
  private summaries = new Map<string, { deposits: number; withdrawals: number; count: number }>();
  
  apply(event: AccountEvent): void {
    if (event.type === 'MONEY_DEPOSITED' || event.type === 'MONEY_WITHDRAWN') {
      const month = event.timestamp.substring(0, 7); // YYYY-MM
      const key = `${event.accountId}:${month}`;
      const current = this.summaries.get(key) || { deposits: 0, withdrawals: 0, count: 0 };
      
      if (event.type === 'MONEY_DEPOSITED') {
        current.deposits += event.amount;
      } else {
        current.withdrawals += event.amount;
      }
      current.count++;
      
      this.summaries.set(key, current);
    }
  }
}
 
// Consumer: Fan-out to all projections
async function consumeAccountEvents(): Promise<void> {
  const balanceProjection = new BalanceProjection();
  const summaryProjection = new MonthlySummaryProjection();
  // ... more projections
  
  // Subscribe from earliest for full rebuild, or from checkpoint for live
  await eventStream.subscribe('account-events', { startFrom: checkpoint }, async (event) => {
    // Fan-out to all projections (same event, multiple handlers)
    balanceProjection.apply(event);
    summaryProjection.apply(event);
    // ... more projections
    
    // Checkpoint for recovery
    await saveCheckpoint(event.position);
  });
}

Fan-Out at Scale: Performance Considerations

As subscriber count grows, fan-out performance becomes critical. Understanding the mechanics helps you design systems that scale efficiently.

Fan-Out Scaling Factors
Factor	Impact	Mitigation
Subscriber count	Linear increase in broker work per message	Hierarchical fan-out; separate topics by domain
Message size	Network bandwidth multiplied by subscribers	Reference pattern (URI instead of payload); compression
Subscriber speed variance	Slow subscribers don't block fast ones (good)	Ensure backpressure per subscription; monitor lag
Acknowledgment overhead	Per-subscription ack tracking	Batch acknowledgments; tune ack deadlines
Message ordering	Ordering constraints limit parallelism	Relax ordering where possible; partition by entity

The Reference Pattern for Large Payloads

When events contain large data (images, documents, batch records), fan-out multiplies bandwidth consumption. The reference pattern separates data storage from event routing:

Store large payload in object storage (S3, GCS, Azure Blob)
Publish event containing only a reference (URI) to the payload
Subscribers fetch payload on demand (with caching)

This keeps the message bus lean and fast, while large data flows directly from storage to consumer.

reference-pattern.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
// Reference Pattern: Large payload via object storage
 
interface LargeDocumentEvent {
  eventId: string;
  eventType: 'DOCUMENT_UPLOADED';
  timestamp: string;
  
  // Metadata (small, included in event)
  documentId: string;
  fileName: string;
  contentType: string;
  fileSizeBytes: number;
  uploadedBy: string;
  
  // Reference to large content (not included in event)
  contentRef: {
    bucket: string;
    key: string;
    region: string;
    presignedUrl?: string; // Optional: pre-signed URL with expiry
  };
}
 
// Publisher: Store content, publish reference
async function publishDocumentUploaded(
  document: Buffer,
  metadata: DocumentMetadata
): Promise<void> {
  // Step 1: Store large content in object storage
  const key = `documents/${metadata.documentId}/${metadata.fileName}`;
  await s3.putObject({
    Bucket: 'documents-bucket',
    Key: key,
    Body: document,
    ContentType: metadata.contentType,
  });
  
  // Step 2: Publish small event with reference
  const event: LargeDocumentEvent = {
    eventId: generateId(),
    eventType: 'DOCUMENT_UPLOADED',
    timestamp: new Date().toISOString(),
    documentId: metadata.documentId,
    fileName: metadata.fileName,
    contentType: metadata.contentType,
    fileSizeBytes: document.length,
    uploadedBy: metadata.userId,
    contentRef: {
      bucket: 'documents-bucket',
      key,
      region: 'us-east-1',
    },
  };
  
  // Event is small (~500 bytes) regardless of document size
  await pubsub.topic('documents.uploaded').publish(event);
}
 
// Consumer: Fetch content on demand
async function processDocumentEvent(event: LargeDocumentEvent): Promise<void> {
  // Only fetch if this consumer needs the content
  if (needsContent(event)) {
    const content = await s3.getObject({
      Bucket: event.contentRef.bucket,
      Key: event.contentRef.key,
    });
    await processContent(content.Body);
  } else {
    // Some consumers only need metadata
    await processMetadataOnly(event);
  }
}

Presigned URLs for Cross-Account Access

Fan-Out Anti-Patterns

Certain patterns seem convenient but lead to fragile, hard-to-maintain systems. Recognizing these anti-patterns helps you avoid common pitfalls.

Anti-Patterns to Avoid

•God Topic: One topic for all events ('events', 'all-messages'). Every consumer receives everything; filtering is impossible; topic becomes a bottleneck and reasoning nightmare. Fix: Domain-specific topics with clear boundaries.
•Polluted Events: Adding fields to events because 'consumer X needs them'. Over time, events become kitchen sinks with fields for every consumer. Fix: Publish clean domain events; let consumers enrich as needed.
•Orchestrated Fan-Out: Producer explicitly publishes to multiple topics based on consumer needs. Producer becomes coupled to all consumers; adding consumers requires producer changes. Fix: Publish once; let subscriptions or routers handle distribution.
•Synchronous Disguised as Async: Producer waits for all consumers to process before continuing. Defeats the purpose of async; reintroduces coupling. Fix: True fire-and-forget; use scatter-gather only when aggregation is actually needed.
•Phantom Subscriptions: Subscriptions for consumers that no longer exist. Messages accumulate indefinitely, wasting resources. Fix: Subscription lifecycle management; monitor and alert on inactive subscriptions.

Anti-Pattern Detection
Symptom	Likely Anti-Pattern	Root Cause
Producer code changes when consumers change	Orchestrated fan-out	Producer knows about consumers
Events have many optional fields	Polluted events	Events designed for consumers, not domain
All consumers process all event types	God topic	Missing topic segmentation
High disk usage on broker	Phantom subscriptions	Stale subscriptions accumulating messages
Producer latency tied to consumer latency	Synchronous disguised as async	Producer waiting for processing

Summary: Fan-Out Patterns

We've explored the major patterns for distributing events to multiple consumers. Let's consolidate the key concepts:

Key Takeaways

•Simple fan-out is the baseline: One topic, many independent subscriptions, each receiving all events. Maximum decoupling, minimum coordination.
•Hierarchical fan-out manages complexity: Event routers translate and redistribute events to domain-specific topics, enabling cleaner boundaries.
•Filtered fan-out reduces waste: Broker-side filtering delivers only relevant events to each subscription, saving bandwidth and processing.
•Scatter-gather adds request-response: When you need aggregated results from multiple services, overlay scatter-gather on top of messaging.
•Event sourcing enables temporal fan-out: Multiple projections from one event stream, with replay capability for new views.
•Reference pattern scales large payloads: Store data in object storage, publish references in events to keep the message bus efficient.

What's Next:

Page Complete

3 / 5