Architecture Overview

Understanding the Symphony

Think of Nexus as a modern symphony hall with advanced technology:

• Storage Rooms (Listeners, History, Cursors): Where instruments and sheet music are stored
• AI Conductor (Prediction Engine): Learns patterns and anticipates the next movement
• Sound System (Priority Scheduler): Routes sounds through different channels (bass, treble, etc.)
• Broadcast Network (Cross-Tab/Teleport): Streams the concert to radio, TV, and online
• Safety Systems (Circuit Breakers, Chaos Monkey): Backup musicians and fire drills

The Problem: Traditional Event Buses Are Dumb Pipes

Standard event libraries are essentially hash maps:

// Oversimplified typical event bus
class SimpleEventBus {
  private listeners = new Map<string, Function[]>();
  
  on(event: string, fn: Function) {
    if (!this.listeners.has(event)) this.listeners.set(event, []);
    this.listeners.get(event)!.push(fn);
  }
  
  emit(event: string, payload: any) {
    this.listeners.get(event)?.forEach(fn => fn(payload));
  }
}

This works for toy examples, but fails in production:

• No priority: A background analytics event blocks critical UI updates
• No resilience: One throw crashes everything
• No history: Late subscribers miss data
• No networking: Can't cross process boundaries
• No intelligence: Repeats the same inefficiencies forever

The Solution: Nexus Architecture

Nexus is built as a layered system where each module enhances the core without adding complexity:

Component Deep Dive

1. Core Engine

The emission pipeline processes every event through these stages:

// Simplified view of emit() method
emit(event, payload, options) {
  // Stage 1: Chaos Testing (Development only)
  if (chaos) simulateFailures();
  
  // Stage 2: Teleportation (Send to server)
  if (teleport) sendToRemote(event, payload);
  
  // Stage 3: AI Learning (Update prediction model)
  if (predictionEnabled) learnPattern(event);
  
  // Stage 4: State Management (Update cursors)
  cursorValues.set(event, payload);
  
  // Stage 5: History (Replay buffer)
  if (replayMemory) addToHistory(event, payload);
  
  // Stage 6: Cross-Tab Sync
  if (broadcastChannel) channel.postMessage({ event, payload });
  
  // Stage 7: Priority-Based Execution
  scheduleByPriority(options.priority, () => {
    // Stage 8: Trigger Listeners
    executeListeners(event, payload);
  });
}

2. Storage Layer

Four specialized data structures:

Structure	Purpose	Type
listeners	Exact event matches	Map<string, Set<{fn, options}>>
wildcards	Pattern matches (e.g., user:*)	Set<{regex, fn, options}>
history	Replay buffer	Map<string, Array<payload>>
cursorValues	Latest values	Map<string, any>

Why this design?

• O(1) lookup for exact matches
• Wildcard support for hierarchical events
• Circular buffer for memory efficiency
• Sync access to latest state

3. Priority Scheduler

Events are scheduled into four lanes:

Execution Order:

1. Critical: Runs immediately (blocks thread) - Use for UI freezes prevention
2. High: Microtask queue (Promise.then) - Runs before next tick
3. Normal: Event loop tick (setTimeout 0) - Standard behavior
4. Background: Idle callback (when CPU free) - Analytics, logging

Real-World Example:

// User clicks button
bus.emit('button:click', { id: 'submit' }, { priority: 'critical' });
// ^ Must run NOW to prevent perceived lag

// Update analytics
bus.emit('analytics:click', data, { priority: 'background' });
// ^ Can wait until CPU is idle

// Fetch data from API
bus.emit('api:request', params, { priority: 'high' });
// ^ Important but shouldn't block UI

4. Intelligence Layer (AI Prediction)

The Markov Chain tracks event sequences:

How it works:

// User does: A → B → A → B → A → B → C
// Nexus learns: "After A, B happens 66%, C happens 33%"

const transitions = new Map();
// Structure: Map<fromEvent, Map<toEvent, count>>

// When confidence > threshold, emit prediction
if (probability >= predictionThreshold) {
  bus.emit(`prediction:${nextEvent}`, { 
    probability, 
    sourceEvent 
  });
}

Use Case: Prefetch the "Add to Cart" API when user hovers over a product (if 80% likely to click).

5. Networking Layer

Cross-Tab Synchronization

// Tab 1
bus.emit('cart:add', { productId: 123 });

// Tab 2 (automatically receives it)
bus.on('cart:add', (product) => {
  updateCartUI(product);
});

Behind the scenes:

Teleportation Bridge

const bus = new Nexus({
  teleport: (event, payload) => {
    // Send to server via WebSocket
    ws.send(JSON.stringify({ type: event, data: payload }));
  }
});

// Any emit() automatically goes to server
bus.emit('chat:message', { text: 'Hello' });
// ^ Sent to WebSocket AND local listeners

Reverse direction (server → client):

ws.onmessage = (msg) => {
  const { type, data } = JSON.parse(msg.data);
  bus.feed(type, data); // Inject from external source
};

6. Resilience Layer

Circuit Breaker (Auto-Retry)

bus.on('api:fetch', fetchHandler, {
  attempts: 3,         // Try 3 times
  backoff: 1000,       // Wait 1s between retries
  fallback: (error) => {
    // All retries failed
    showOfflineMessage();
  }
});

Execution flow:

Chaos Monkey

Injects failures during development:

const bus = new Nexus({
  chaos: {
    dropRate: 0.1,      // 10% packet loss
    maxDelay: 2000,     // Up to 2s latency
    exclude: ['auth:*'] // Never break auth
  }
});

Why? If your app works with 10% packet loss, it will be bulletproof in production.

Data Flow Example

Let's trace a complete event from emission to execution:

// User action
bus.emit('product:view', { id: 123 }, { priority: 'high' });

Step-by-step execution:

1. Chaos Monkey (if enabled): Might drop or delay
2. Teleport: Send to server WebSocket
3. AI Prediction: Record transition from previous event
4. Cursor Update: Set cursorValues['product:view'] = { id: 123 }
5. History: Push to replay buffer
6. Cross-Tab: Broadcast to other tabs
7. Scheduler: Queue in Microtask (high priority)
8. Execution:
   • Find exact listeners for 'product:view'
   • Find wildcards matching 'product:*'
   • Run each with retry logic
9. Complete: Return control to caller

Memory Management

Nexus uses bounded buffers to prevent memory leaks:

// History buffer is circular
if (stack.length > this.config.replayMemory) {
  stack.shift(); // Remove oldest
}

Memory footprint:

• Listeners: O(n) where n = number of subscriptions
• History: O(m × k) where m = event types, k = replayMemory size
• Transitions: O(e²) where e = unique events (capped by usage)
• Cursors: O(m) where m = event types with cursors

Performance Characteristics

Operation	Time Complexity	Notes
emit()	O(1) + O(L)	L = listener count
on()	O(1)	Hash map insert
request()	O(1) + O(L)	Creates temp listener
cursor.value	O(1)	Direct map access
Wildcard match	O(W × R)	W = wildcards, R = regex test

Optimization tips:

• Use exact event names over wildcards when possible
• Set replayMemory only as high as needed
• Disable predictionThreshold if not using AI
• Use background priority for non-critical work

Next Steps

Now that you understand the internal architecture, let's explore specific patterns:

• RPC Pattern - Request/Reply communication
• Priority Lanes - Execution scheduling deep dive
• Cursors & State - Reactive state management

Architecture Checklist

When designing your event system, ask:

• [ ] Do I need priority scheduling? (UI performance)
• [ ] Do I need replay? (Late subscribers)
• [ ] Do I need cross-tab sync? (Multi-window apps)
• [ ] Do I need teleportation? (Client/Server bridge)
• [ ] Do I need AI prediction? (Prefetching/optimization)
• [ ] Do I need resilience? (Retries/fallbacks)
• [ ] Do I need chaos testing? (QA/staging environments)

Nexus gives you all of these as opt-in features - only pay for what you use.