CloddsBot Signal Bus: Purpose and Implementation in the Trading Pipeline

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 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 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, 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 (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, 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:

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:

// 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:

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

Key Source Files

• 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: Defines the public type definitions (TickUpdate, OrderbookUpdate, TradingSignal, SignalBus) used throughout the codebase.
• tests/unit/signal-router.test.ts: Contains unit tests validating the bus’s filtering, rejection, and error-handling behavior.
• 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 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: 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 lines 56–88, ensures no stale listeners remain from the previous connection.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}