Architecture Utilities

Optional developer utilities for architecture documentation and workflow definition.

These methods are not required for core Nexus usage. They provide convenience features for documenting event flows and defining declarative event chains.

---

Workflow Definition: scenario()

The scenario() method provides a fluent API for defining event chains declaratively.

What It Does

Creates automatic event forwarding from one event to another. When the trigger event is emitted, the target event is automatically emitted.

bus.scenario()
  .when('user:login')
  .thenEmit('analytics:track', (loginData) => ({
    event: 'login',
    userId: loginData.username,
    timestamp: Date.now()
  }));

Behavior

• Automatically subscribes to the trigger event
• Forwards (or transforms) the payload to the target event
• Populates internal graph data for visualization
• Returns chainable API for multiple scenarios

Example: User Authentication Flow

import { Nexus } from '@caeligo/nexus-orchestrator';

const bus = new Nexus();

// Define event chain declaratively
bus.scenario()
  .when('auth:login')
  .thenEmit('session:create')
  .when('session:create')
  .thenEmit('user:load');

// Trigger the chain
bus.emit('auth:login', { username: 'alice' });
// Automatically emits: session:create → user:load

When to Use

• Documenting event flow relationships
• Creating simple event forwarding rules
• Generating architecture diagrams (see generateGraph())

Limitations

• Creates permanent subscriptions (no unsubscribe method)
• For complex logic, use standard on() + emit() instead

Note: This is an optional/advanced utility. Standard event subscription with on() and emit() is recommended for most use cases.

---

Architecture Visualization: generateGraph()

The generateGraph() method exports a Mermaid.js diagram string representing the event flow architecture.

What It Does

Returns a string containing Mermaid.js syntax that visualizes:

• Event subscriptions (from on() calls)
• Event chains (from scenario() definitions)

const diagram = bus.generateGraph();
console.log(diagram);
// Output:
// graph TD
//   user_login --> Listener
//   session_create --> Listener

Output Format

Mermaid.js graph TD (top-down graph) syntax. Can be embedded in Markdown documentation or rendered with Mermaid tools.

Example: Export Architecture Diagram

import { Nexus } from '@caeligo/nexus-orchestrator';

const bus = new Nexus();

// Define some event flows
bus.on('user:login', handleLogin);
bus.on('user:logout', handleLogout);

bus.scenario()
  .when('user:login')
  .thenEmit('analytics:track');

// Export diagram
const mermaidCode = bus.generateGraph();

// Save to file or embed in docs
console.log(mermaidCode);

Output:

graph TD
  user_login --> Listener
  user_logout --> Listener
  user_login -->|Triggers| analytics_track

Integration with VitePress

This repository uses VitePress with the Mermaid plugin. The output can be embedded directly in documentation:

```mermaid
graph TD
  user_login --> Listener
  user_login -->|Triggers| analytics_track
```

Data Source

The graph is built from:

• All on() subscriptions (creates event --> Listener edges)
• All scenario() chains (creates event -->|Triggers| event edges)

When to Use

• Generating architecture documentation automatically
• Visualizing event flow relationships
• Debugging complex event chains

Note: This is an optional/advanced utility for documentation purposes only.

---

Comparison with Core APIs

Approach	Use Case
on() + emit()	Standard event handling (recommended)
scenario()	Declarative event chains (optional)
generateGraph()	Architecture documentation (optional)

These utilities complement the core event bus but are not required for typical usage.

---

Next Steps

For standard event bus usage, refer to:

• Getting Started - Basic usage
• RPC Pattern - Request/reply
• Priority Lanes - Execution scheduling