WebSocket Sync Server

Relevant source files

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

• crates/arbor-server/src/server.rs
• crates/arbor-server/src/sync_server.rs
• crates/arbor-cli/src/commands.rs
• crates/arbor-server/README.md
• crates/arbor-mcp/src/lib.rs
• extensions/arbor-vscode/src/extension.ts

The WebSocket Sync Server is a high-performance, real-time synchronization component of the Arbor ecosystem designed to act as the "Source of Truth" for visualizers and IDE extensions. Its primary purpose is to broadcast graph updates and state changes whenever the filesystem is modified, ensuring that external tools like the Logic Forest Visualizer or the VS Code extension remain in sync with the current state of the codebase.

Sources: crates/arbor-server/src/sync_server.rs:1-10, crates/arbor-server/README.md:14-20

By hosting a WebSocket server and monitoring the filesystem through a debounced watcher, the Sync Server enables "execution-aware analysis" and live updates across multiple clients simultaneously. It supports streaming large graphs in chunks and provides a "Spotlight" feature to highlight specific code nodes across connected clients.

Sources: crates/arbor-server/src/sync_server.rs:105-115, crates/arbor-cli/src/commands.rs:350-360

Architecture and Components

The Sync Server architecture is built around three main concurrent tasks: the WebSocket server for client communication, a filesystem watcher for detecting changes, and a background indexer for updating the shared graph state.

Core System Structure

The diagram above shows the relationship between the internal tasks and the shared graph state. Sources: crates/arbor-server/src/sync_server.rs:150-175

Component Descriptions

Component	Description
FS Watcher	Monitors the filesystem for created, changed, or deleted files using the notify crate.
Background Indexer	Processes events from the watcher, re-parses affected files, and updates the SharedGraph.
WebSocket Server	Manages client connections, performs initial graph handshakes, and broadcasts delta updates.
SyncServerHandle	A cloneable handle used by external modules (like MCP) to trigger "Spotlight" focus events.

Sources: crates/arbor-server/src/sync_server.rs:105-145, crates/arbor-mcp/src/lib.rs:35-45

Server Configuration

The server behavior is controlled by the SyncServerConfig struct, which defines binding addresses, paths to monitor, and file filtering rules.

Option	Type	Default	Description
addr	SocketAddr	127.0.0.1:8080	The address the WebSocket server binds to.
watch_path	PathBuf	.	The root directory to watch for file changes.
debounce_ms	u64	150	Wait time (ms) to group multiple file events.
extensions	Vec<String>	ts, rs, py, etc.	Filter for relevant source file extensions.

Sources: crates/arbor-server/src/sync_server.rs:25-50, crates/arbor-cli/src/commands.rs:355-365

Communication Protocol

The Sync Server uses a specific message format for broadcasting information to clients. All messages are wrapped in a BroadcastMessage enum, which is serialized to JSON with a type tag.

Connection Handshake

When a client connects, the server follows a strict handshake sequence to prevent overwhelming the client with a large graph before it is ready.

Message Types

The protocol supports several broadcast types to handle live updates:

Message Type	Description
Hello	Metadata containing version and total node/edge counts.
NodeBatch / EdgeBatch	Used for chunked transmission of large datasets (50 nodes or 100 edges per batch).
GraphUpdate	Broadcasts delta updates when files change (contains changed_files and new graph stats).
FocusNode	Known as "Spotlight", triggers the visualizer/IDE to focus on a specific node ID and line.
IndexerStatus	Streams real-time progress of the background indexing phase.

Sources: crates/arbor-server/src/sync_server.rs:55-100

Filesystem Synchronization Logic

The synchronization process relies on a debounced file watcher to prevent excessive re-indexing during rapid file writes (e.g., during a "Save All" operation).

Debouncing Process

1. Event Detection: The notify crate sends raw events to the internal watcher loop.
2. Filtering: The server checks the file extension against the configured extensions list.
3. Pending Queue: Events are placed in a HashMap with a timestamp.
4. Debounce Interval: The server periodically checks if now - timestamp >= debounce_ms.
5. Execution: Once the interval passes, a WatcherEvent is sent to the background indexer.

Sources: crates/arbor-server/src/sync_server.rs:435-480

Re-indexing Workflow

When a file change is processed:

• The background indexer uses ArborParser to extract new symbols and relations from the file.
• The SharedGraph is locked for writing.
• g.remove_file(path) clears existing nodes associated with that file to prevent duplicates.
• New nodes and edges are added to the graph.
• A GraphUpdate message is broadcast to all clients with is_delta: true.

Sources: crates/arbor-server/src/sync_server.rs:495-550

External Integration (Spotlight)

The Sync Server provides a mechanism for other systems, such as the Model Context Protocol (MCP) server, to influence the UI of connected clients.

Spotlight Mechanism

The SyncServerHandle allows external components to call spotlight_node. This sends a FocusNode message to clients like the VS Code extension, which then uses the highlightSpotlight function to open the specific file and apply a "golden glow" decoration to the relevant line.

Conclusion

The WebSocket Sync Server is the backbone of Arbor's real-time capabilities. By combining efficient filesystem watching, debounced background indexing, and a chunked streaming protocol, it ensures that architectural visualizations and AI-assisted navigation tools remain perfectly aligned with the source code. Its "Spotlight" feature bridges the gap between AI analysis and developer UI, providing a seamless feedback loop during code exploration.

Sources: crates/arbor-server/src/sync_server.rs:1-20, crates/arbor-cli/src/commands.rs:350-380