The Loom Dashboard

Relevant source files

The following files were used as context for generating this wiki page:

• core/src/dashboard/README.md
• core/examples/dashboard_demo.rs
• core/tests/dashboard_unit_test.rs
• loom-py/src/loom/cli/README.md
• core/src/dashboard/static/index.html
• core/Cargo.toml

The Loom Dashboard provides real-time observability for Loom Core. It is designed to give developers a live view of the event stream, an animated map of agent interactions, and quick insights into the overall system health. This allows for monitoring how threads of execution move through the agent orchestration stack directly from a web browser, without needing to leave the terminal environment where Loom is often run.

The dashboard is an essential tool for debugging, monitoring, and understanding the complex, asynchronous communication patterns within a multi-agent system built on Loom.

Sources: core/src/dashboard/README.md:3-5

Architecture

The dashboard's architecture is split between a Rust backend that serves data and a React-based frontend that visualizes it. The backend components are tightly integrated with Loom Core's EventBus to capture and process telemetry data in real-time. The frontend is a static bundle of assets served by the backend, which consumes data via a set of specific API endpoints.

Sources: core/src/dashboard/README.md:27-35

This diagram illustrates the high-level data flow from the Loom Core EventBus to the user's browser.

Backend Components

The backend is composed of several key Rust components that work together to collect, process, and serve observability data.

Component	Purpose
EventBroadcaster	Publishes trimmed event payloads to all connected dashboard clients over Server-Sent Events (SSE).
FlowTracker	Records (source, target, topic) communication edges between agents and components. It automatically prunes old data to manage memory.
TopologyBuilder	Reads from the AgentDirectory to build and surface a snapshot of the live agent roster and their topic subscriptions.
DashboardServer	An axum-based HTTP server that hosts the static frontend assets and exposes the data APIs.

Sources: core/src/dashboard/README.md:29-35, core/Cargo.toml:19

EventBroadcaster

The EventBroadcaster is responsible for streaming live events to the dashboard frontend. It uses a broadcast channel to efficiently send DashboardEvent structs to any connected client.

• Capacity: It is initialized with a fixed capacity buffer.
• Subscriptions: It allows multiple clients to subscribe and receive events.
• Resilience: It handles cases with zero subscribers without errors and correctly manages the subscriber count as clients connect and disconnect.

Unit tests confirm that it can deliver various event types, including EventPublished, AgentRegistered, and ToolInvoked, to all active subscribers.

Sources: core/tests/dashboard_unit_test.rs:17-109, core/src/dashboard/README.md:30

FlowTracker

The FlowTracker is a stateful component that builds a graph of interactions within the system. It maintains an in-memory graph with automatic Time-To-Live (TTL) and bounded topic lists to prevent uncontrolled memory growth.

• Flow Recording: It tracks flows as (source, target, topic) tuples, incrementing a counter for repeated identical flows.
• Node Management: It automatically creates nodes for new sources and targets, inferring their type (e.g., Agent, Router, LLM). It also tracks the topics associated with each node.
• Memory Management:
  • Flow Expiration: Edges (flows) expire after 60 seconds of inactivity.
  • Node Expiration: Nodes expire after 120 seconds of inactivity.
  • Topic Capping: Each node stores a maximum of the 20 most recent topics to ensure predictable JSON payload sizes.

The FlowTracker is crucial for powering the "Agent Network Graph" on the dashboard.

Sources: core/src/dashboard/README.md:31, 60-64, core/tests/dashboard_unit_test.rs:115-274

TopologyBuilder

The TopologyBuilder generates a snapshot of the agent network topology based on the central AgentDirectory. This snapshot includes a list of all registered agents and the connections (edges) between them, which are derived from their topic subscriptions. This data is used to render the static agent network and their relationships.

Sources: core/src/dashboard/README.md:32, core/tests/dashboard_unit_test.rs:280-353

API Endpoints

The DashboardServer exposes a simple API for the frontend to consume. All data stays on the server, and the browser only renders the JSON delivered via these endpoints.

Endpoint	Method	Description
/api/events/stream	GET	A Server-Sent Events (SSE) stream that pushes live DashboardEvent objects to the client.
/api/flow	GET	Returns a JSON object representing the current communication flow graph from the FlowTracker. The frontend polls this every 2.5 seconds.
/api/topology	GET	Returns a JSON object with the current agent topology from the TopologyBuilder.
/api/metrics	GET	Returns placeholder metrics. This is intended to be extended with real telemetry data.

Sources: core/src/dashboard/README.md:37-38, 62

The following sequence diagram shows the interaction between the frontend and the backend API.

Frontend

The dashboard frontend is a modern web application built with React and Vite. It is designed to be responsive and suitable for long-running monitoring sessions.

• Technology Stack: React, Vite, and the shadcn/ui component kit with Tailwind CSS.
• Build Process: The frontend is developed in core/src/dashboard/frontend/. Running npm run build generates optimized, hashed static assets in core/src/dashboard/static/, which are then embedded into the Rust server binary.
• SSE Client: The React application maintains exactly one EventSource connection for the event stream, with resilient logic to close the old connection before reconnecting. This is a key operational detail to prevent bugs.

Sources: core/src/dashboard/README.md:9, 34, 56-58, 70-75, core/src/dashboard/static/index.html

Key UI Components

The dashboard presents several key visualizations:

• Event Flow: A streaming list of events with filters per-agent, Quality of Service (QoS) badges, and hints for correlation and threads.
• Agent Communications: A chronological rendering of tool calls, outputs, and inter-agent messages.
• Agent Network Graph: An animated canvas view showing active nodes and recent communication flows within a 60-second window.
• Metrics: Displays key performance indicators like events/sec (client-derived), active agents, and routing decisions.

Sources: core/src/dashboard/README.md:19-24

Integration and Configuration

The dashboard can be easily integrated into any service using Loom Core. It is bootstrapped and configured via environment variables.

Service Integration

To add the dashboard to a Loom application, you instantiate the DashboardServer and its dependencies, then spawn it as a separate Tokio task. The EventBus must be configured to forward events to the dashboard's EventBroadcaster.

// From core/examples/dashboard_demo.rs
let mut event_bus = EventBus::new().await?;
let agent_directory = Arc::new(AgentDirectory::new());

// Create dashboard broadcaster and flow tracker
let broadcaster = EventBroadcaster::new(1000);
let flow_tracker = Arc::new(FlowTracker::new());

// Connect EventBus to Dashboard
event_bus.set_dashboard_broadcaster(broadcaster.clone());

// Start Dashboard server
let config = DashboardConfig::from_env();
let dashboard = DashboardServer::new(
    config.clone(),
    broadcaster,
    agent_directory.clone(),
    span_collector, // Optional span collector for telemetry
)
.with_flow_tracker(flow_tracker.clone());

tokio::spawn(async move {
    if let Err(e) = dashboard.serve().await {
        eprintln!("Dashboard error: {}", e);
    }
});

// To record flows for the graph, call:
flow_tracker.record_flow("source_agent", "target_agent", "some.topic").await;

Sources: core/examples/dashboard_demo.rs:16-50, 53, core/src/dashboard/README.md:42-53

Configuration

The dashboard server is configured using environment variables.

Environment Variable	Default	Description
LOOM_DASHBOARD	false	Set to true to enable and bootstrap the dashboard server.
LOOM_DASHBOARD_HOST	127.0.0.1	The bind address for the HTTP server.
LOOM_DASHBOARD_PORT	3030	The listening port for the HTTP server.

Sources: core/src/dashboard/README.md:55-58, core/tests/dashboard_unit_test.rs:360-410

The loom-py CLI tool automatically manages this configuration when using the loom up command, which starts the full runtime including the dashboard.

Sources: loom-py/src/loom/cli/README.md:27-29

Testing

The dashboard includes a comprehensive suite of unit tests for its backend components, located in core/tests/dashboard_unit_test.rs.

• EventBroadcaster: 8 tests covering subscriptions, broadcasting, and subscriber management.
• FlowTracker: 11 tests covering flow recording, state cleanup, and memory limits.
• TopologyBuilder: 5 tests covering snapshot generation from the agent directory.
• DashboardConfig: 6 tests covering default values and environment variable parsing.

Sources: core/src/dashboard/README.md:80-90, core/tests/dashboard_unit_test.rs