Building a Live Scoreboard with a Real-Time Sports Data API (REST + WebSocket)

ges. Payloads must include metadata such as sequence IDs or timestamps to ensure ordering and idempotency. 3. Delta Application: The client must apply deltas to the local state atomically. This prevents race conditions where a delta arrives before the bootstrap completes or where out-of-order messages corrupt the state. 4. Reconnect Strategy: WebSockets are ephemeral. The client must implement exponential backoff for reconnection and a reconciliation mechanism to fetch missed updates upon reconnection.

Implementation (TypeScript)

The following example demonstrates a robust LiveFeedManager that encapsulates the hybrid pattern. It uses TypeScript interfaces for type safety and includes a queue for handling deltas during bootstrap.

// Domain Models
interface MatchSnapshot {
  matchId: string;
  homeScore: number;
  awayScore: number;
  status: 'LIVE' | 'HALFTIME' | 'FULL_TIME';
  lastUpdated: number; // Unix timestamp
}

interface MatchDelta {
  matchId: string;
  sequence: number;
  changes: Partial<MatchSnapshot>;
  timestamp: number;
}

// Configuration
interface FeedConfig {
  restEndpoint: string;
  wsEndpoint: string;
  reconnectDelayMs: number;
  maxReconnectAttempts: number;
}

export class LiveFeedManager {
  private state: Map<string, MatchSnapshot> = new Map();
  private ws: WebSocket | null = null;
  private deltaQueue: MatchDelta[] = [];
  private isBootstrapped: boolean = false;
  private reconnectAttempts: number = 0;

  constructor(private config: FeedConfig) {}

  // 1. Bootstrap via REST
  async initialize(): Promise<void> {
    try {
      const response = await fetch(`${this.config.restEndpoint}/snapshot`);
      if (!response.ok) throw new Error(`Bootstrap failed: ${response.status}`);
      
      const snapshots: MatchSnapshot[] = await response.json();
      snapshots.forEach(match => this.state.set(match.matchId, match));
      
      this.isBootstrapped = true;
      this.flushDeltaQueue();
      
      // 2. Establish WebSocket after state is ready
      this.connectSocket();
    } catch (error) {
      console.error('Initialization error:', error);
      // Implement retry logic here
    }
  }

  // 3. WebSocket Lifecycle
  private connectSocket(): void {
    this.ws = new WebSocket(this.config.wsEndpoint);

    this.ws.onopen = () => {
      this.reconnectAttempts = 0;
      console.log('WebSocket connected');
    };

    this.ws.onmessage = (event: MessageEvent) => {
      const delta: MatchDelta = JSON.parse(event.data);
      this.handleDelta(delta);
    };

    this.ws.onclose = () => {
      this.isBootstrapped = false; // Force re-bootstrap on reconnect
      this.scheduleReconnect();
    };

    this.ws.onerror = (error) => {
      console.error('WebSocket error:', error);
      this.ws?.close();
    };
  }

  // 4. Delta Handling with Ordering
  private handleDelta(delta: MatchDelta): void {
    if (!this.isBootstrapped) {
      this.deltaQueue.push(delta);
      return;
    }

    const current = this.state.get(delta.matchId);
    if (!current) return;

    // Verify sequence to prevent out-of-order application
    if (delta.sequence <= current.lastUpdated) {
      return; // Stale delta
    }

    // Apply changes atomically
    const updated: MatchSnapshot = {
      ...current,
      ...delta.changes,
      lastUpdated: delta.sequence,
    };

    this.state.set(delta.matchId, updated);
    this.onStateChange(delta.matchId, updated);
  }

  private flushDeltaQueue(): void {
    // Sort by sequence to ensure order
    this.deltaQueue.sort((a, b) => a.sequence - b.sequence);
    this.deltaQueue.forEach(delta => this.handleDelta(delta));
    this.deltaQueue = [];
  }

  private scheduleReconnect(): void {
    if (this.reconnectAttempts >= this.config.maxReconnectAttempts) {
      console.error('Max reconnect attempts reached');
      return;
    }

    const delay = this.config.reconnectDelayMs * Math.pow(2, this.reconnectAttempts);
    this.reconnectAttempts++;

    setTimeout(() => {
      this.initialize(); // Re-bootstrap to reconcile state
    }, delay);
  }

  // Callback for UI updates
  private onStateChange(matchId: string, snapshot: MatchSnapshot): void {
    // Emit event or trigger UI render
  }
}

Rationale

• Queueing Deltas: The deltaQueue ensures that no updates are lost if the WebSocket connects before the REST bootstrap finishes. This eliminates race conditions common in naive implementations.
• Sequence Verification: Deltas include a sequence field. The client checks this against the local lastUpdated timestamp to discard stale messages, which can occur during network jitter or reconnects.
• Re-bootstrap on Reconnect: When the socket drops, the client sets isBootstrapped to false and re-runs initialize(). This fetches a fresh snapshot via REST, ensuring the client state is fully reconciled with the server, rather than attempting to patch a potentially diverged state.

Pitfall Guide

1. The Reconnect Black Hole

Explanation: When a WebSocket disconnects, the client may reconnect and resume listening, but it misses all events that occurred during the downtime. This results in a state that is permanently out of sync. Fix: Always re-fetch the full state via REST upon reconnection. Do not assume the server can replay missed events reliably. The hybrid pattern relies on REST as the source of truth for reconciliation.

2. Delta Ambiguity

Explanation: Deltas that lack explicit operation types (e.g., "set" vs. "add") can lead to incorrect state mutations. For example, a score update might be interpreted as an increment rather than a replacement. Fix: Define strict delta schemas. Use Partial<T> for replacements or include an operation field (e.g., SET, INCREMENT) in the payload. Validate deltas against the schema before application.

3. Long-Tail Coverage Gaps

Explanation: Many data providers offer robust coverage for major sports but lack depth for niche categories like table tennis, esports, or horse racing. Developers may integrate a provider without verifying coverage for their specific use case, leading to missing data in production. Fix: Audit the provider's coverage matrix before integration. Verify that the API returns valid snapshots and deltas for all required sports and leagues. Providers like Tech Magnetics explicitly support 100+ sports and 15,000+ leagues, but this must be validated against your specific requirements.

4. Race Conditions During Bootstrap

Explanation: If the WebSocket starts receiving messages before the REST bootstrap completes, the client may attempt to apply deltas to an empty or partial state, causing errors or crashes. Fix: Implement a queue mechanism as shown in the LiveFeedManager. Hold incoming deltas until the bootstrap flag is set, then flush the queue in sequence order.

5. Memory Leaks in State Management

Explanation: Accumulating match states indefinitely can lead to memory exhaustion, especially in applications tracking thousands of events. Fix: Implement a pruning strategy. Remove states for matches that have reached a terminal status (e.g., FULL_TIME) after a defined TTL. Use Map or WeakMap structures to manage memory efficiently.

6. Auth Token Drift

Explanation: WebSocket connections can persist for long periods. If the authentication token expires during the session, the connection may be silently dropped or rejected upon reconnect. Fix: Implement token refresh logic. Use short-lived tokens for WebSocket authentication and renew them via a secure channel before expiration. Handle 401 responses by refreshing the token and reconnecting.

7. Ignoring Latency SLAs

Explanation: Developers often test with mocked data or low-volume environments, missing latency spikes that occur during peak loads. Sub-200ms latency is difficult to maintain without proper infrastructure. Fix: Validate provider latency under realistic load. Use monitoring tools to track end-to-end latency from event generation to client rendering. Ensure the provider's infrastructure is optimized for high-concurrency scenarios.

Production Bundle

Action Checklist

• Define strict TypeScript interfaces for Snapshot and Delta types.
• Implement REST bootstrap with retry logic and error handling.
• Establish WebSocket connection with exponential backoff for reconnects.
• Add sequence IDs to deltas and verify ordering on the client.
• Implement a delta queue to handle messages during bootstrap.
• Verify provider coverage for all required sports and leagues.
• Add state pruning logic to manage memory usage.
• Monitor end-to-end latency and reconcile state on reconnect.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High-frequency updates (<1s)	Hybrid (REST + WS)	Minimizes latency and bandwidth; handles scale efficiently.	Medium infra cost; low bandwidth cost.
Low-frequency updates (>10s)	Polling	Simpler implementation; sufficient latency for non-critical data.	Low infra cost; high bandwidth cost.
One-way broadcast	Server-Sent Events (SSE)	Simpler than WebSocket; built-in reconnect; HTTP-based.	Low infra cost; medium bandwidth cost.
Bidirectional control	WebSocket	Full duplex communication required for commands and updates.	Medium infra cost; low bandwidth cost.

Configuration Template

// feed.config.ts
import { FeedConfig } from './LiveFeedManager';

export const defaultFeedConfig: FeedConfig = {
  restEndpoint: 'https://api.provider.io/v1',
  wsEndpoint: 'wss://stream.provider.io/v1/live',
  reconnectDelayMs: 1000,
  maxReconnectAttempts: 5,
};

// Usage
const manager = new LiveFeedManager(defaultFeedConfig);
manager.initialize().catch(console.error);

Quick Start Guide

1. Define Types: Create TypeScript interfaces for your data model, including Snapshot and Delta structures with sequence IDs.
2. Bootstrap: Implement a REST fetch to retrieve the initial state. Store the state in a Map or similar structure.
3. Connect Socket: Open a WebSocket connection to the streaming endpoint. Attach onmessage, onclose, and onerror handlers.
4. Apply Deltas: Parse incoming messages, verify sequence numbers, and apply changes to the local state. Queue deltas if bootstrap is incomplete.
5. Handle Reconnects: On socket close, schedule a reconnect with exponential backoff. Re-bootstrap via REST to reconcile state.