System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Arbor is a local-first impact analysis engine designed to transform codebases into semantic dependency graphs. Unlike traditional text-based search or vector-based RAG systems, Arbor utilizes a Code Property Graph (CPG) to provide structural certainty regarding execution paths, caller/callee relationships, and cross-file symbol resolution. This architectural approach enables deterministic analysis of the "blast radius" for any code change.
Sources: README.md:16-30, PR_DESCRIPTION.md:5-10
Core Component Hierarchy
The system is organized into specialized Rust crates that handle different stages of the code-to-graph transformation and data consumption.
Component Responsibilities
| Component | Responsibility | Key Technologies |
|---|---|---|
| arbor-core | AST parsing and entity extraction | Tree-sitter |
| arbor-watcher | File system monitoring and change detection | notify crate, ignore crate |
| arbor-graph | In-memory graph management and persistence | petgraph, sled, bincode |
| arbor-server | WebSocket and JSON-RPC API exposure | WebSocket, JSON-RPC |
| arbor-mcp | AI agent integration bridge | Model Context Protocol |
| arbor-cli | Primary user interface and orchestration | Rust |
| arbor-gui / Visualizer | Interactive graph exploration and UI | Flutter, egui |
Sources: crates/arbor-core/README.md, crates/arbor-watcher/README.md, crates/arbor-graph/README.md, crates/arbor-server/README.md, crates/arbor-mcp/README.md
High-Level Data Flow
The following diagram illustrates the flow from source code to actionable intelligence through various system layers.
The diagram shows how arbor-watcher triggers arbor-core to parse code, which then populates arbor-graph. This graph is persisted via sled and consumed by various interfaces.
Sources: crates/arbor-watcher/README.md, crates/arbor-graph/README.md, crates/arbor-cli/src/commands.rs:340-380
The Analysis Engine (arbor-graph & arbor-core)
At the heart of Arbor is the ArborGraph, which utilizes petgraph for in-memory graph operations. It manages a Global Symbol Table that maps Fully Qualified Names (FQNs) to unique Node IDs, allowing for robust cross-file resolution of imports, inheritance, and calls.
Node and Edge Types
Nodes represent code entities (Functions, Classes, Structs, etc.), while edges represent their relationships:
- FlowsTo: Represents control flow paths.
- DataDependency: Represents data flow analysis.
- Call/Import/Inheritance: Standard structural relationships.
Sources: PR_DESCRIPTION.md:20-35, crates/arbor-graph/README.md, crates/arbor-graph/src/lib.rs:1-25
Impact Analysis Logic
Arbor performs bidirectional Breadth-First Search (BFS) to determine the "blast radius" of a symbol modification. This analysis categorizes affected nodes by:
- Upstream (Callers): Nodes that depend on the target.
- Downstream (Dependencies): Nodes the target depends on.
- Severity: Classified as Direct (1 hop), Transitive (2-3 hops), or Distant (4+ hops).
Sources: CHANGELOG.md:7-15, crates/arbor-cli/src/commands.rs:593-610
Distribution and Connectivity (arbor-server & arbor-mcp)
Arbor provides multiple ways for external tools to consume graph data.
Model Context Protocol (MCP) Bridge
The arbor-mcp crate implements the Model Context Protocol, allowing AI agents to perform structural queries over stdio.
This sequence shows an AI agent requesting an impact analysis, which simultaneously triggers a "spotlight" in the visualizer while returning structured data to the agent.
Sources: crates/arbor-mcp/src/lib.rs:40-60, 160-220
WebSocket and RPC Protocol
The arbor-server handles real-time synchronization between the indexed codebase and front-end clients like the Flutter-based Logic Forest visualizer or the VS Code extension. It supports standard JSON-RPC methods such as discover, impact, and context.
Sources: crates/arbor-server/README.md, crates/arbor-cli/src/commands.rs:345-365
Persistence Layer
Arbor implements a GraphStore using the sled embedded database to ensure persistence across sessions.
- Binary Serialization: Uses
bincodefor high-performance state saving. - Incremental Sync: Only "dirty" nodes (affected by file changes) are rewritten to disk using atomic batches and a file-to-node index (
f:{file} -> [n:{id}]).
Sources: PR_DESCRIPTION.md:15-18, crates/arbor-graph/README.md
User Interfaces
Command Line Interface (CLI)
The arbor-cli acts as the orchestrator for the system.
arbor index: Triggers the initial scan and graph construction.arbor bridge --viz: Simultaneously starts the MCP bridge, the WebSocket sync server, and the visualizer.arbor refactor <symbol>: Provides a textual summary of the impact analysis, including confidence scores and architectural roles (e.g., Entry Point, Utility, Core Logic).
Sources: crates/arbor-cli/src/commands.rs:46-100, 580-600, crates/arbor-cli/README.md
Native GUI & Visualizer
The system includes two graphical interfaces:
- Arbor GUI: A lightweight
eguiapplication for quick symbol search and impact reports. - Logic Forest (Flutter): A high-performance visualizer utilizing Barnes-Hut QuadTree force layouts for rendering 100k+ nodes and Level of Detail (LOD) optimizations to maintain 60 FPS during navigation.
Sources: crates/arbor-gui/src/app.rs, PR_DESCRIPTION.md:25-30
Conclusion
Arbor's architecture is a decoupled, crate-based system that prioritizes structural accuracy over heuristic guessing. By combining Tree-sitter's precise parsing with a graph-native storage engine and modern communication protocols like MCP and WebSockets, Arbor provides a robust platform for both human developers and AI agents to understand and navigate complex codebases safely.
Sources: README.md:90-100, PR_DESCRIPTION.md:5-10