# anandb71/arbor architecture

> Architecture diagram of the GitHub repository anandb71/arbor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anandb71/arbor
- Repository: https://github.com/anandb71/arbor

## Overview

1. **Top-level shape**
   Arbor is a Rust monorepo centered on a shared indexing and graph-analysis engine. Most runtime logic lives in Rust crates under `crates/`, with separate client surfaces for CLI, server/MCP, desktop GUI, and a Flutter-based visualizer.

2. **Core architecture**
   The architectural center is `arbor-core` plus `arbor-graph`. `arbor-core` handles source parsing and language-specific extraction, while `arbor-graph` turns extracted symbols and references into a queryable dependency graph with ranking, confidence, impact, slicing, and search support.

3. **Source ingestion and parsing**
   Input starts from a local codebase on disk. `arbor-core` contains the parser pipeline, per-language adapters under `src/languages/`, and a `fallback_parser` for weaker support cases, so the system can ingest multiple ecosystems without depending on a single language frontend.

4. **Graph construction and storage**
   Parsed nodes and edges flow into `arbor-graph`’s builder/store layer. The graph crate also maintains derived structures such as a symbol table, search index, heuristics, and confidence scoring, which are used to answer impact and traversal queries efficiently.

5. **Analysis layer**
   Query-facing logic is built on top of the graph, not on raw text search. The main architectural outputs are caller/callee traversal, path finding, blast-radius analysis, and “slice” style dependency views that explain what changes are likely to affect.

6. **CLI as the primary operator**
   `arbor-cli` is the main user entry point and drives setup, diff, refactor, check, and summary-style workflows. It is the command boundary that invokes the shared core to index a repo, inspect changes, and gate risky edits, including Git-aware checks for uncommitted or PR diffs.

7. **Incremental updating**
   `arbor-watcher` provides the always-on indexing path. It watches the filesystem, feeds change events into an `indexer`, and keeps the graph cache fresh so Arbor can support near-real-time updates instead of only full re-scans.

8. **Service and protocol layer**
   `arbor-server` packages the core engine behind a reusable protocol/handler/server boundary, with a `sync_server` suggesting incremental or stateful synchronization. `arbor-mcp` wraps that capability for MCP clients via stdio, exposing the same graph reasoning to agents and IDE assistants without duplicating analysis logic.

9. **User interfaces**
   There are two visualization frontends: `arbor-gui` is a Rust desktop GUI, and `visualizer/` is a Flutter/Dart app with its own graph rendering, force layout, and websocket service. Both sit above the same graph data model and are presentation layers rather than separate analysis engines.

10. **Language and ecosystem boundaries**
   Language support is broad and explicit: Rust, TypeScript, Python, Go, Java, C/C++, C#, Dart, and several fallback-parsed languages. The repo is also packaged for multiple distribution channels—Cargo, npm wrapper, Homebrew, Scoop, Docker, VS Code extension, and GitHub Actions—which makes the core engine reusable across CLI, IDE, CI, and agent workflows.

11. **Tests and operational surfaces**
   The workspace includes integration tests for CLI commands and GitHub workflows for Rust CI, release automation, MCP validation, marketplace publishing, and container builds. That tells you the repo is designed as a local-first analysis engine with multiple delivery surfaces, not a single application binary.

Main entry points: [`crates/arbor-graph/src/query.rs`](https://github.com/anandb71/arbor/blob/main/crates/arbor-graph/src/query.rs) (Analysis), [`crates/arbor-graph/src/builder.rs`](https://github.com/anandb71/arbor/blob/main/crates/arbor-graph/src/builder.rs) (Graph builder), [`crates/arbor-cli/src/main.rs`](https://github.com/anandb71/arbor/blob/main/crates/arbor-cli/src/main.rs) (CLI), [`crates/arbor-core/src/parser.rs`](https://github.com/anandb71/arbor/blob/main/crates/arbor-core/src/parser.rs) (Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core engine"]
  node_arbor_core_parser["Parser<br/>rust parsing pipeline<br/>[parser.rs]"]
  node_arbor_core_languages["Languages<br/>rust language adapters<br/>[mod.rs]"]
  node_arbor_core_fallback["Fallback<br/>[fallback_parser.rs]"]
  node_arbor_graph_builder[("Graph builder<br/>rust build/store<br/>[builder.rs]")]
  node_arbor_graph_query{{"Analysis<br/>rust query engine<br/>[query.rs]"}}
  node_arbor_graph_index["Indexes<br/>rust search/index<br/>[search_index.rs]"]
end

subgraph group_surfaces["Command and service surfaces"]
  node_arbor_cli["CLI<br/>rust command app<br/>[main.rs]"]
  node_arbor_watcher["Watcher<br/>rust incremental indexer<br/>[watcher.rs]"]
  node_arbor_server["Server<br/>[server.rs]"]
  node_arbor_sync_server["Sync server<br/>rust sync layer<br/>[sync_server.rs]"]
  node_arbor_mcp["MCP<br/>rust stdio wrapper<br/>[lib.rs]"]
end

subgraph group_ui["User interfaces"]
  node_arbor_gui["GUI<br/>rust desktop app<br/>[main.rs]"]
  node_visualizer_app["Visualizer<br/>flutter app<br/>[main.dart]"]
  node_visualizer_graph(("Graph view<br/>dart rendering<br/>[graph_widget.dart]"))
  node_visualizer_ws["Websocket<br/>dart sync client"]
end

subgraph group_distribution["Packaging"]
  node_vscode_ext["VS Code<br/>extension host<br/>[extension.ts]"]
  node_npm_wrapper["NPM wrapper<br/>packaging shell<br/>[arbor.js]"]
  node_homebrew_formula["Homebrew<br/>package formula<br/>[arbor.rb]"]
end

node_arbor_core_languages -->|"feed parsers"| node_arbor_core_parser
node_arbor_core_fallback -->|"fallback input"| node_arbor_core_parser
node_arbor_core_parser -->|"emit symbols"| node_arbor_graph_builder
node_arbor_graph_builder -->|"populate indexes"| node_arbor_graph_index
node_arbor_graph_builder -->|"serve graph"| node_arbor_graph_query
node_arbor_graph_index -->|"accelerate queries"| node_arbor_graph_query
node_arbor_cli -->|"index repo"| node_arbor_core_parser
node_arbor_cli -->|"inspect changes"| node_arbor_graph_query
node_arbor_watcher -->|"refresh graph"| node_arbor_graph_builder
node_arbor_server -->|"answer requests"| node_arbor_graph_query
node_arbor_sync_server -->|"sync state"| node_arbor_server
node_arbor_mcp -->|"wrap protocol"| node_arbor_server
node_arbor_gui -->|"visualize analysis"| node_arbor_graph_query
node_visualizer_app -->|"render graph"| node_visualizer_graph
node_visualizer_app -->|"stream data"| node_visualizer_ws
node_visualizer_ws -->|"sync graph"| node_arbor_server
node_vscode_ext -->|"assistant bridge"| node_arbor_mcp
node_npm_wrapper -->|"launch cli"| node_arbor_cli
node_homebrew_formula -->|"install cli"| node_arbor_cli

click node_arbor_core_parser "https://github.com/anandb71/arbor/blob/main/crates/arbor-core/src/parser.rs"
click node_arbor_core_languages "https://github.com/anandb71/arbor/blob/main/crates/arbor-core/src/languages/mod.rs"
click node_arbor_core_fallback "https://github.com/anandb71/arbor/blob/main/crates/arbor-core/src/fallback_parser.rs"
click node_arbor_graph_builder "https://github.com/anandb71/arbor/blob/main/crates/arbor-graph/src/builder.rs"
click node_arbor_graph_query "https://github.com/anandb71/arbor/blob/main/crates/arbor-graph/src/query.rs"
click node_arbor_graph_index "https://github.com/anandb71/arbor/blob/main/crates/arbor-graph/src/search_index.rs"
click node_arbor_cli "https://github.com/anandb71/arbor/blob/main/crates/arbor-cli/src/main.rs"
click node_arbor_watcher "https://github.com/anandb71/arbor/blob/main/crates/arbor-watcher/src/watcher.rs"
click node_arbor_server "https://github.com/anandb71/arbor/blob/main/crates/arbor-server/src/server.rs"
click node_arbor_sync_server "https://github.com/anandb71/arbor/blob/main/crates/arbor-server/src/sync_server.rs"
click node_arbor_mcp "https://github.com/anandb71/arbor/blob/main/crates/arbor-mcp/src/lib.rs"
click node_arbor_gui "https://github.com/anandb71/arbor/blob/main/crates/arbor-gui/src/main.rs"
click node_visualizer_app "https://github.com/anandb71/arbor/blob/main/visualizer/lib/main.dart"
click node_visualizer_graph "https://github.com/anandb71/arbor/blob/main/visualizer/lib/graph/graph_widget.dart"
click node_visualizer_ws "https://github.com/anandb71/arbor/blob/main/visualizer/lib/services/websocket_service.dart"
click node_vscode_ext "https://github.com/anandb71/arbor/blob/main/extensions/arbor-vscode/src/extension.ts"
click node_npm_wrapper "https://github.com/anandb71/arbor/blob/main/packaging/npm/bin/arbor.js"
click node_homebrew_formula "https://github.com/anandb71/arbor/blob/main/packaging/homebrew/arbor.rb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_arbor_core_parser,node_arbor_core_languages,node_arbor_core_fallback,node_arbor_graph_builder,node_arbor_graph_query,node_arbor_graph_index toneBlue
class node_arbor_cli,node_arbor_watcher,node_arbor_server,node_arbor_sync_server,node_arbor_mcp toneAmber
class node_arbor_gui,node_visualizer_app,node_visualizer_graph,node_visualizer_ws toneMint
class node_vscode_ext,node_npm_wrapper,node_homebrew_formula toneRose
```

## Components

### Core engine

Parsing, graph construction, and query analysis.

- [Parser](https://github.com/anandb71/arbor/blob/main/crates/arbor-core/src/parser.rs): rust parsing pipeline · Source ingestion, language adapters, and fallback parsing. · `crates/arbor-core/src/parser.rs`
- [Languages](https://github.com/anandb71/arbor/blob/main/crates/arbor-core/src/languages/mod.rs): rust language adapters · Per-language extractors for supported ecosystems. · `crates/arbor-core/src/languages/mod.rs`
- [Fallback](https://github.com/anandb71/arbor/blob/main/crates/arbor-core/src/fallback_parser.rs): rust fallback parser · Weaker parsing path for partially supported inputs. · `crates/arbor-core/src/fallback_parser.rs`
- [Graph builder](https://github.com/anandb71/arbor/blob/main/crates/arbor-graph/src/builder.rs): rust build/store · Builds and stores symbol and edge data from extracted nodes. · `crates/arbor-graph/src/builder.rs`
- [Analysis](https://github.com/anandb71/arbor/blob/main/crates/arbor-graph/src/query.rs): rust query engine · Traversal, path finding, impact, and slice-style dependency queries. · `crates/arbor-graph/src/query.rs`
- [Indexes](https://github.com/anandb71/arbor/blob/main/crates/arbor-graph/src/search_index.rs): rust search/index · Symbol table, search index, ranking, heuristics, and confidence support. · `crates/arbor-graph/src/search_index.rs`

### Command and service surfaces

CLI and protocol layers that invoke the shared engine.

- [CLI](https://github.com/anandb71/arbor/blob/main/crates/arbor-cli/src/main.rs): rust command app · Primary local operator for indexing, diffing, refactoring, and checks. · `crates/arbor-cli/src/main.rs`
- [Watcher](https://github.com/anandb71/arbor/blob/main/crates/arbor-watcher/src/watcher.rs): rust incremental indexer · Filesystem monitor that keeps the graph fresh from change events. · `crates/arbor-watcher/src/watcher.rs`
- [Server](https://github.com/anandb71/arbor/blob/main/crates/arbor-server/src/server.rs): rust protocol server · Reusable handler and server boundary for graph reasoning. · `crates/arbor-server/src/server.rs`
- [Sync server](https://github.com/anandb71/arbor/blob/main/crates/arbor-server/src/sync_server.rs): rust sync layer · Stateful or incremental synchronization path on top of the server. · `crates/arbor-server/src/sync_server.rs`
- [MCP](https://github.com/anandb71/arbor/blob/main/crates/arbor-mcp/src/lib.rs): rust stdio wrapper · Exposes Arbor capabilities to MCP clients and agents. · `crates/arbor-mcp/src/lib.rs`

### User interfaces

Desktop and visual frontends over the same graph model.

- [GUI](https://github.com/anandb71/arbor/blob/main/crates/arbor-gui/src/main.rs): rust desktop app · Native desktop interface over the shared analysis engine. · `crates/arbor-gui/src/main.rs`
- [Visualizer](https://github.com/anandb71/arbor/blob/main/visualizer/lib/main.dart): flutter app · Flutter/Dart visualization frontend for graph exploration. · `visualizer/lib/main.dart`
- [Graph view](https://github.com/anandb71/arbor/blob/main/visualizer/lib/graph/graph_widget.dart): dart rendering · Force layout, painting, and graph interaction in the visualizer. · `visualizer/lib/graph/graph_widget.dart`
- [Websocket](https://github.com/anandb71/arbor/blob/main/visualizer/lib/services/websocket_service.dart): dart sync client · Live data transport used by the visualizer frontend. · `visualizer/lib/services/websocket_service.dart`

### Packaging

Repository entry points and release/distribution wrappers.

- [VS Code](https://github.com/anandb71/arbor/blob/main/extensions/arbor-vscode/src/extension.ts): extension host · Editor extension surface for Arbor features. · `extensions/arbor-vscode/src/extension.ts`
- [NPM wrapper](https://github.com/anandb71/arbor/blob/main/packaging/npm/bin/arbor.js): packaging shell · Node-based launcher and install wrapper for the CLI. · `packaging/npm/bin/arbor.js`
- [Homebrew](https://github.com/anandb71/arbor/blob/main/packaging/homebrew/arbor.rb): package formula · Homebrew distribution entry for the CLI. · `packaging/homebrew/arbor.rb`

## Connections

- Languages → Parser: feed parsers · Language-specific extractors plug into the shared parsing pipeline.
- Fallback → Parser: fallback input · Fallback parsing handles weaker or partially supported source files.
- Parser → Graph builder: emit symbols · Parsed nodes and references are handed off for graph construction.
- Graph builder → Indexes: populate indexes · The store layer also maintains symbol and search-oriented structures.
- Graph builder → Analysis: serve graph · Built graph state becomes the basis for traversal and impact queries.
- Indexes → Analysis: accelerate queries · Indexes and heuristics support faster graph analysis.
- CLI → Parser: index repo · CLI commands drive parsing and indexing of local codebases.
- CLI → Analysis: inspect changes · CLI workflows query the graph for diff, refactor, and summary actions.
- Watcher → Graph builder: refresh graph · Filesystem events are turned into incremental indexing updates.
- Server → Analysis: answer requests · The server exposes graph reasoning through its protocol boundary.
- Sync server → Server: sync state · Incremental synchronization builds on the main server implementation.
- MCP → Server: wrap protocol · MCP reuses the server-side analysis rather than duplicating it.
- GUI → Analysis: visualize analysis · The desktop UI sits on top of the shared graph engine.
- Visualizer → Graph view: render graph · The Flutter app delegates layout and painting to its graph view.
- Visualizer → Websocket: stream data · The app receives graph updates over websocket transport.
- Websocket → Server: sync graph · The visualizer talks to the shared server layer for live data.
- VS Code → MCP: assistant bridge · The extension surface connects editor workflows to Arbor capabilities.
- NPM wrapper → CLI: launch cli · The npm packaging layer wraps the main command-line entry point.
- Homebrew → CLI: install cli · Homebrew distributes the command-line tool as a packaged binary.