# CloddsBot Signal Bus: Purpose and Implementation in the Trading Pipeline

> Discover the CloddsBot signal bus purpose: a typed, event-driven hub decoupling data ingestion from processing. Learn how it fans out events, isolates errors, and manages lifecycles in your trading pipeline.

- Repository: [AL/CloddsBot](https://github.com/alsk1992/CloddsBot)
- Tags: internals
- Published: 2026-09-13

---

**The CloddsBot signal bus is a typed, event-driven hub that decouples market data ingestion from processing by fanning out FeedManager events to multiple consumers while providing error isolation and lifecycle management.**

The signal bus in the [alsk1992/CloddsBot](https://github.com/alsk1992/CloddsBot) repository serves as the central nervous system for real-time trading data. This TypeScript-based architecture component connects the **FeedManager** (which supplies raw market data) to downstream strategies, ensuring that every registered consumer receives consistent data without needing direct access to the feed source.

## Core Responsibilities of the CloddsBot Signal Bus

The signal bus implementation in [`src/gateway/signal-bus.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/gateway/signal-bus.ts) fulfills five critical functions within the trading pipeline.

### Fan-Out Distribution from FeedManager

When the FeedManager emits raw `price` or `orderbook` updates, the bus re-emits these as standardized `tick` and `orderbook` events. This **fan-out pattern** ensures that tick processors, order-book viewers, and trading-signal handlers all receive identical data simultaneously without direct coupling to the FeedManager.

In [`src/gateway/signal-bus.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/gateway/signal-bus.ts), the `bus.connectFeeds` method (lines 56–74) wires the FeedManager’s `price` and `orderbook` events to the bus’s own emitters, creating a clean separation between data ingestion and data processing modules.

### Type-Safe Event Definitions

The bus enforces strict data contracts through explicit payload shapes defined in [`src/types/signal-bus.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/types/signal-bus.ts) (lines 11–43). These **TypeScript interfaces** include:

- `TickUpdate`: Standardized price tick data
- `OrderbookUpdate`: Order book depth and spread information
- `TradingSignal`: Processed buy/sell recommendations

By exporting these types from [`src/types/signal-bus.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/types/signal-bus.ts), the CloddsBot signal bus ensures compile-time verification of event payloads across the entire codebase, preventing runtime type errors in trading strategies.

### Error Isolation and Fault Tolerance

A single misbehaving listener cannot crash the entire trading system. The bus overrides the standard `emit` method (lines 28–53) to wrap each listener invocation in a try-catch block. When a listener throws an error, the bus logs the exception and continues delivering the event to remaining listeners, maintaining system stability even when individual strategies fail.

### Lifecycle Management

The bus provides `connectFeeds` and `disconnectFeeds` methods to safely manage FeedManager attachments. This design allows the bot to re-attach to a new FeedManager instance—such as during runtime configuration reloads or hot-swapping data sources—without leaving stale event listeners that could cause memory leaks or duplicate processing (implemented in lines 56–88).

### Developer-Friendly Subscription API

Rather than requiring developers to use raw `EventEmitter.on` calls, the bus exposes semantic wrapper methods. The `onTick`, `onOrderbook`, and `onSignal` methods (lines 90–94) provide clear, self-documenting entry points for consumers, improving code readability and reducing the likelihood of event-name typos.

## Implementation Guide: Using the CloddsBot Signal Bus

### Creating and Wiring the Bus

Initialize the signal bus and attach it to your FeedManager using the `createSignalBus` factory function:

```typescript
import { createSignalBus } from './gateway/signal-bus';
import { FeedManager } from './feeds';

const bus = createSignalBus();
const feeds = new FeedManager(/* …config… */);

// Attach the feeds to the bus (once per runtime)
bus.connectFeeds(feeds);

```

### Registering Event Consumers

Subscribe to specific event types using the typed helper methods. Each callback receives a fully typed payload:

```typescript
// Consume price tick updates
bus.onTick((update) => {
  console.log(`[${update.platform}] ${update.marketId} price: ${update.price}`);
});

// Consume trading signals with error isolation
bus.onSignal((signal) => {
  if (signal.direction === 'buy') {
    executeBuyOrder(signal);
  } else {
    executeSellOrder(signal);
  }
});

```

### Safe Disconnection and Cleanup

Before hot-reloading or shutting down, cleanly detach the FeedManager to prevent memory leaks:

```typescript
bus.disconnectFeeds();   // removes all feed listeners

```

## Key Source Files

- **[`src/gateway/signal-bus.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/gateway/signal-bus.ts)**: Contains the core `SignalBus` class implementation, including the safe-emit wrapper, FeedManager wiring logic, and subscription helpers.
- **[`src/types/signal-bus.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/types/signal-bus.ts)**: Defines the public type definitions (`TickUpdate`, `OrderbookUpdate`, `TradingSignal`, `SignalBus`) used throughout the codebase.
- **[`tests/unit/signal-router.test.ts`](https://github.com/alsk1992/CloddsBot/blob/main/tests/unit/signal-router.test.ts)**: Contains unit tests validating the bus’s filtering, rejection, and error-handling behavior.
- **[`src/feeds/index.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/feeds/index.ts)**: Produces the raw `price` and `orderbook` events consumed by the bus (indirect dependency).

## Summary

- The CloddsBot signal bus acts as a **central communication backbone** between the FeedManager and downstream trading components.
- It implements **fan-out distribution** to broadcast market data to multiple consumers simultaneously.
- **TypeScript type definitions** in [`src/types/signal-bus.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/types/signal-bus.ts) enforce data integrity across the trading pipeline.
- **Error isolation** prevents individual listener crashes from destabilizing the entire bot.
- **Lifecycle methods** (`connectFeeds`/`disconnectFeeds`) enable safe runtime reconfiguration without memory leaks.

## Frequently Asked Questions

### What is the primary purpose of the CloddsBot signal bus?

The primary purpose is to **decouple data ingestion from data processing**. By sitting between the FeedManager and trading strategies, the bus allows multiple components to react to the same market data independently, supporting a modular architecture where strategies can be added or removed without modifying the feed source.

### How does the signal bus handle errors in listeners?

The bus overrides the native `emit` method to wrap each listener in a try-catch block. If a listener throws an exception, the bus captures the error, logs it for debugging, and **continues executing remaining listeners**. This ensures that a bug in one trading strategy cannot crash the entire market data pipeline.

### What types of events does the CloddsBot signal bus support?

The bus supports three primary event types defined in [`src/types/signal-bus.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/types/signal-bus.ts): **tick events** (price updates), **orderbook events** (market depth changes), and **signal events** (processed trading recommendations). Each event type has a strictly defined TypeScript interface ensuring consistent data structures.

### How do I safely reconnect the signal bus to a new FeedManager?

Call `bus.disconnectFeeds()` to remove all existing FeedManager listeners, then instantiate your new FeedManager and call `bus.connectFeeds(newFeedManager)`. This lifecycle pattern, implemented in [`src/gateway/signal-bus.ts`](https://github.com/alsk1992/CloddsBot/blob/main/src/gateway/signal-bus.ts) lines 56–88, ensures no stale listeners remain from the previous connection.