# garthdb/ferrograph architecture

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

- Interactive diagram: https://gitdiagram.com/garthdb/ferrograph
- Repository: https://github.com/garthdb/ferrograph
- Video tour (about a minute): https://gitdiagram.com/garthdb/ferrograph/video

## Overview

Ferrograph indexes Rust projects into a queryable code knowledge graph, exposed through CLI commands and an MCP server. The main workflow discovers source files, extracts AST entities, resolves module and code relationships, and stores the resulting graph; users then query, search, inspect impact, or review changes against a base revision. The graph also supports watch-driven reindexing and optional git coupling and trait mapping. The sampled pipeline shows phase ordering, but not every phase implementation; those links are limited to relationships documented by the README or pipeline entry point.

Main entry points: [`src/pipeline/mod.rs`](https://github.com/garthdb/ferrograph/blob/main/src/pipeline/mod.rs) (Index Pipeline), [`src/config.rs`](https://github.com/garthdb/ferrograph/blob/main/src/config.rs) (CLI Dispatch), [`src/ops.rs`](https://github.com/garthdb/ferrograph/blob/main/src/ops.rs) (Shared Operations), [`src/graph/store.rs`](https://github.com/garthdb/ferrograph/blob/main/src/graph/store.rs) (CozoDB Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Interfaces"]
  node_cli["CLI Dispatch<br/>[config.rs]"]
  node_mcp["MCP Server<br/>[mod.rs]"]
  node_watch["Watch Reindexing<br/>[watch.rs]"]
  node_claude["Claude Skill<br/>[claude.rs]"]
end

subgraph group_index["Indexing"]
  node_discovery["File Discovery<br/>[discovery.rs]"]
  node_ast["AST Extraction<br/>[ast.rs]"]
  node_pipeline["Index Pipeline<br/>[mod.rs]"]
end

subgraph group_analysis["Graph Analysis"]
  node_module_resolution["Module Resolution<br/>[modules.rs]"]
  node_call_graph["Call Graph<br/>[calls.rs]"]
  node_relationship_phases["Type And Macro Edges"]
  node_ownership["Ownership And Borrows<br/>[borrows.rs]"]
  node_git_coupling["Git Coupling<br/>[git_coupling.rs]"]
end

subgraph group_storage["Graph Storage"]
  node_schema["Graph Schema<br/>[schema.rs]"]
  node_store[("CozoDB Store<br/>[store.rs]")]
end

subgraph group_insights["Queries And Review"]
  node_queries["Graph Queries<br/>[query.rs]"]
  node_search["Text Search<br/>[mod.rs]"]
  node_ops["Shared Operations<br/>[ops.rs]"]
  node_pr_review["Change Review<br/>[pr.rs]"]
  node_format["Output Formats<br/>[format.rs]"]
end

node_user(("Engineer / Agent"))

node_user -->|"runs commands"| node_cli
node_user -->|"uses tools"| node_mcp
node_user -->|"watches project"| node_watch
node_cli -->|"requests indexing"| node_pipeline
node_watch -->|"reindexes changes"| node_pipeline
node_pipeline -->|"discovers files"| node_discovery
node_pipeline -->|"extracts syntax"| node_ast
node_pipeline -->|"resolves modules"| node_module_resolution
node_pipeline -->|"builds calls"| node_call_graph
node_pipeline -->|"resolves edges"| node_relationship_phases
node_pipeline -->|"resolves borrows"| node_ownership
node_pipeline -.->|"optionally analyzes"| node_git_coupling
node_pipeline -->|"builds graph"| node_store
node_pipeline -.->|"uses node types"| node_schema
node_cli -->|"runs queries"| node_ops
node_mcp -.->|"serves operations"| node_ops
node_mcp -->|"searches payloads"| node_search
node_ops -->|"runs text search"| node_search
node_ops -->|"requests graph data"| node_queries
node_queries -->|"runs queries"| node_store
node_search -->|"searches nodes"| node_store
node_store -->|"uses graph types"| node_schema
node_pr_review -->|"opens graph"| node_store
node_pr_review -->|"computes impact"| node_ops
node_cli -->|"reviews changes"| node_pr_review
node_cli -->|"manages skill"| node_claude
node_cli -->|"selects output"| node_format
node_pr_review -->|"formats reports"| node_format

click node_cli "https://github.com/garthdb/ferrograph/blob/main/src/config.rs"
click node_mcp "https://github.com/garthdb/ferrograph/blob/main/src/mcp/mod.rs"
click node_watch "https://github.com/garthdb/ferrograph/blob/main/src/watch.rs"
click node_discovery "https://github.com/garthdb/ferrograph/blob/main/src/pipeline/discovery.rs"
click node_ast "https://github.com/garthdb/ferrograph/blob/main/src/pipeline/ast.rs"
click node_module_resolution "https://github.com/garthdb/ferrograph/blob/main/src/pipeline/modules.rs"
click node_call_graph "https://github.com/garthdb/ferrograph/blob/main/src/pipeline/calls.rs"
click node_relationship_phases "https://github.com/garthdb/ferrograph/tree/main/src/pipeline"
click node_ownership "https://github.com/garthdb/ferrograph/blob/main/src/pipeline/borrows.rs"
click node_git_coupling "https://github.com/garthdb/ferrograph/blob/main/src/pipeline/git_coupling.rs"
click node_pipeline "https://github.com/garthdb/ferrograph/blob/main/src/pipeline/mod.rs"
click node_schema "https://github.com/garthdb/ferrograph/blob/main/src/graph/schema.rs"
click node_store "https://github.com/garthdb/ferrograph/blob/main/src/graph/store.rs"
click node_queries "https://github.com/garthdb/ferrograph/blob/main/src/graph/query.rs"
click node_search "https://github.com/garthdb/ferrograph/blob/main/src/search/mod.rs"
click node_ops "https://github.com/garthdb/ferrograph/blob/main/src/ops.rs"
click node_pr_review "https://github.com/garthdb/ferrograph/blob/main/src/pr.rs"
click node_format "https://github.com/garthdb/ferrograph/blob/main/src/format.rs"
click node_claude "https://github.com/garthdb/ferrograph/blob/main/src/claude.rs"

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_cli,node_mcp,node_watch,node_claude toneBlue
class node_discovery,node_ast,node_pipeline toneAmber
class node_module_resolution,node_call_graph,node_relationship_phases,node_ownership,node_git_coupling toneMint
class node_schema,node_store toneRose
class node_queries,node_search,node_ops,node_pr_review,node_format,node_user toneIndigo
```

## Components

### Interfaces

- [CLI Dispatch](https://github.com/garthdb/ferrograph/blob/main/src/config.rs): `src/config.rs`
- [MCP Server](https://github.com/garthdb/ferrograph/blob/main/src/mcp/mod.rs): `src/mcp/mod.rs`
- [Watch Reindexing](https://github.com/garthdb/ferrograph/blob/main/src/watch.rs): `src/watch.rs`
- [Claude Skill](https://github.com/garthdb/ferrograph/blob/main/src/claude.rs): `src/claude.rs`

### Indexing

- [File Discovery](https://github.com/garthdb/ferrograph/blob/main/src/pipeline/discovery.rs): `src/pipeline/discovery.rs`
- [AST Extraction](https://github.com/garthdb/ferrograph/blob/main/src/pipeline/ast.rs): `src/pipeline/ast.rs`
- [Index Pipeline](https://github.com/garthdb/ferrograph/blob/main/src/pipeline/mod.rs): `src/pipeline/mod.rs`

### Graph Analysis

- [Module Resolution](https://github.com/garthdb/ferrograph/blob/main/src/pipeline/modules.rs): `src/pipeline/modules.rs`
- [Call Graph](https://github.com/garthdb/ferrograph/blob/main/src/pipeline/calls.rs): `src/pipeline/calls.rs`
- [Type And Macro Edges](https://github.com/garthdb/ferrograph/tree/main/src/pipeline): `src/pipeline`
- [Ownership And Borrows](https://github.com/garthdb/ferrograph/blob/main/src/pipeline/borrows.rs): `src/pipeline/borrows.rs`
- [Git Coupling](https://github.com/garthdb/ferrograph/blob/main/src/pipeline/git_coupling.rs): `src/pipeline/git_coupling.rs`

### Graph Storage

- [Graph Schema](https://github.com/garthdb/ferrograph/blob/main/src/graph/schema.rs): `src/graph/schema.rs`
- [CozoDB Store](https://github.com/garthdb/ferrograph/blob/main/src/graph/store.rs): `src/graph/store.rs`

### Queries And Review

- [Graph Queries](https://github.com/garthdb/ferrograph/blob/main/src/graph/query.rs): `src/graph/query.rs`
- [Text Search](https://github.com/garthdb/ferrograph/blob/main/src/search/mod.rs): `src/search/mod.rs`
- [Shared Operations](https://github.com/garthdb/ferrograph/blob/main/src/ops.rs): `src/ops.rs`
- [Change Review](https://github.com/garthdb/ferrograph/blob/main/src/pr.rs): `src/pr.rs`
- [Output Formats](https://github.com/garthdb/ferrograph/blob/main/src/format.rs): `src/format.rs`

### Other components

- **Engineer / Agent**

## Connections

- Engineer / Agent → CLI Dispatch: runs commands (evidence: `README.md`)
- Engineer / Agent → MCP Server: uses tools (evidence: `README.md`)
- Engineer / Agent → Watch Reindexing: watches project (evidence: `README.md`)
- CLI Dispatch → Index Pipeline: requests indexing (evidence: `src/config.rs`)
- Watch Reindexing → Index Pipeline: reindexes changes (evidence: `src/watch.rs`)
- Index Pipeline → File Discovery: discovers files (evidence: `src/pipeline/mod.rs`)
- Index Pipeline → AST Extraction: extracts syntax (evidence: `src/pipeline/mod.rs`)
- Index Pipeline → Module Resolution: resolves modules (evidence: `src/pipeline/mod.rs`)
- Index Pipeline → Call Graph: builds calls (evidence: `src/pipeline/mod.rs`)
- Index Pipeline → Type And Macro Edges: resolves edges (evidence: `src/pipeline/mod.rs`)
- Index Pipeline → Ownership And Borrows: resolves borrows (evidence: `src/pipeline/mod.rs`)
- Index Pipeline → Git Coupling: optionally analyzes (evidence: `src/pipeline/mod.rs`)
- Index Pipeline → CozoDB Store: builds graph (evidence: `src/pipeline/mod.rs`)
- Index Pipeline → Graph Schema: uses node types
- CLI Dispatch → Shared Operations: runs queries (evidence: `src/config.rs`)
- MCP Server → Shared Operations: serves operations (evidence: `src/mcp/mod.rs`)
- MCP Server → Text Search: searches payloads (evidence: `src/mcp/mod.rs`)
- Shared Operations → Text Search: runs text search (evidence: `src/ops.rs`)
- Shared Operations → Graph Queries: requests graph data (evidence: `src/ops.rs`)
- Graph Queries → CozoDB Store: runs queries (evidence: `src/graph/query.rs`)
- Text Search → CozoDB Store: searches nodes (evidence: `src/search/mod.rs`)
- CozoDB Store → Graph Schema: uses graph types (evidence: `src/graph/store.rs`)
- Change Review → CozoDB Store: opens graph (evidence: `src/pr.rs`)
- Change Review → Shared Operations: computes impact (evidence: `src/pr.rs`)
- CLI Dispatch → Change Review: reviews changes (evidence: `src/config.rs`)
- CLI Dispatch → Claude Skill: manages skill (evidence: `src/config.rs`)
- CLI Dispatch → Output Formats: selects output (evidence: `src/config.rs`)
- Change Review → Output Formats: formats reports (evidence: `src/pr.rs`)