# backbencher-hq/backbencher-brain architecture

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

- Interactive diagram: https://gitdiagram.com/backbencher-hq/backbencher-brain
- Repository: https://github.com/backbencher-hq/backbencher-brain

## Overview

Backbencher Brain (`bb`) indexes a project’s source into a per-project SQLite database, then provides code-intelligence results through CLI, MCP, LSP, and library-facing runtime features. The main workflow is source parsing and indexing, followed by graph, search, and evidence-based queries; health, semantic retrieval, visualization, editing, security analysis, and other documented capabilities are separate branches. The excerpts support key orchestration and storage relationships, but not every subsystem’s internal wiring, so those links are limited to README-documented flows.

Main entry points: [`src/cli/index.ts`](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/cli/index.ts) (CLI), [`src/brain/database.ts`](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/brain/database.ts) (Project Database), [`src/mcp/server.ts`](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/mcp/server.ts) (MCP Server), [`src/ast/parallel-indexer.ts`](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/ast/parallel-indexer.ts) (Parallel Indexer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["CLI<br/>[index.ts]"]
  node_mcp["MCP Server<br/>[server.ts]"]
  node_mcp_registry["Tool Registry<br/>[tool-registry.ts]"]
  node_lsp["LSP Server<br/>[server.ts]"]
end

subgraph group_index["Indexing"]
  node_parallel["Parallel Indexer"]
  node_language["Language Detection"]
  node_ast_engine["AST Engine<br/>[engine.ts]"]
  node_grammars["Tree-sitter Grammars"]
end

subgraph group_store["Index and Contracts"]
  node_database[("Project Database<br/>[database.ts]")]
  node_project_id["Project Identity<br/>[project-id.ts]"]
  node_contracts["Intelligence Contracts<br/>[contracts.ts]"]
  node_evidence["Evidence Provenance<br/>[evidence.ts]"]
end

subgraph group_query["Intelligence"]
  node_graph["Relationship Graph<br/>[graph-engine.ts]"]
  node_search["Search"]
  node_semantic["Semantic Retrieval<br/>[engine.ts]"]
  node_health["Health and Freshness<br/>[health-provider.ts]"]
  node_visualization["Visualization"]
end

subgraph group_analysis["Analysis and Maintenance"]
  node_editing["Code Editing<br/>[edit-engine.ts]"]
  node_security["Security Analysis<br/>[engine.ts]"]
  node_patterns["Pattern Analysis<br/>[orphans.ts]"]
  node_migration["Migration"]
end

node_developer(("Repository User"))

node_developer -->|"runs commands"| node_cli
node_developer -->|"connects host"| node_mcp
node_developer -->|"uses editor"| node_lsp
node_cli -->|"indexes project"| node_parallel
node_parallel -.->|"detects languages"| node_language
node_parallel -.->|"parses files"| node_ast_engine
node_ast_engine -->|"uses parsers"| node_grammars
node_parallel -->|"stores index"| node_database
node_cli -->|"opens index"| node_database
node_mcp -->|"resolves project"| node_project_id
node_mcp -->|"checks index"| node_database
node_mcp -->|"registers tools"| node_mcp_registry
node_lsp -->|"opens index"| node_database
node_lsp -->|"resolves project"| node_project_id
node_database -->|"resolves data path"| node_project_id
node_cli -.->|"queries relationships"| node_graph
node_cli -->|"searches index"| node_search
node_cli -->|"reports health"| node_health
node_cli -->|"requests embeddings"| node_semantic
node_database -->|"supplies index rows"| node_graph
node_database -->|"supplies index rows"| node_visualization
node_database -->|"supplies index state"| node_health
node_database -->|"supplies index rows"| node_patterns
node_database -->|"stores embeddings"| node_semantic
node_semantic -.->|"returns answers"| node_contracts
node_graph -->|"returns relationships"| node_contracts
node_contracts -->|"carries provenance"| node_evidence
node_cli -->|"renders index"| node_visualization
node_cli -->|"edits source"| node_editing
node_cli -->|"analyzes security"| node_security
node_cli -->|"finds patterns"| node_patterns
node_cli -->|"migrates code"| node_migration

click node_cli "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/cli/index.ts"
click node_mcp "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/mcp/server.ts"
click node_mcp_registry "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/mcp/tool-registry.ts"
click node_lsp "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/lsp/server.ts"
click node_parallel "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/ast/parallel-indexer.ts"
click node_language "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/ast/language-detection.ts"
click node_ast_engine "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/ast/engine.ts"
click node_grammars "https://github.com/backbencher-hq/backbencher-brain/tree/main/grammars"
click node_database "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/brain/database.ts"
click node_project_id "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/util/project-id.ts"
click node_contracts "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/contracts.ts"
click node_evidence "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/evidence.ts"
click node_graph "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/graph/graph-engine.ts"
click node_search "https://github.com/backbencher-hq/backbencher-brain/tree/main/src/intelligence/search"
click node_semantic "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/brain/semantic/engine.ts"
click node_health "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/health/health-provider.ts"
click node_visualization "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/visualization/visualization-engine.ts"
click node_editing "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/edit/edit-engine.ts"
click node_security "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/security/rebuild/engine.ts"
click node_patterns "https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/patterns/orphans.ts"
click node_migration "https://github.com/backbencher-hq/backbencher-brain/tree/main/src/intelligence/migration"

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_mcp_registry,node_lsp,node_developer toneBlue
class node_parallel,node_language,node_ast_engine,node_grammars toneAmber
class node_database,node_project_id,node_contracts,node_evidence toneMint
class node_graph,node_search,node_semantic,node_health,node_visualization toneRose
class node_editing,node_security,node_patterns,node_migration toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/cli/index.ts): `src/cli/index.ts`
- [MCP Server](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/mcp/server.ts): `src/mcp/server.ts`
- [Tool Registry](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/mcp/tool-registry.ts): `src/mcp/tool-registry.ts`
- [LSP Server](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/lsp/server.ts): `src/lsp/server.ts`

### Indexing

- [Parallel Indexer](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/ast/parallel-indexer.ts): `src/ast/parallel-indexer.ts`
- [Language Detection](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/ast/language-detection.ts): `src/ast/language-detection.ts`
- [AST Engine](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/ast/engine.ts): `src/ast/engine.ts`
- [Tree-sitter Grammars](https://github.com/backbencher-hq/backbencher-brain/tree/main/grammars): `grammars`

### Index and Contracts

- [Project Database](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/brain/database.ts): `src/brain/database.ts`
- [Project Identity](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/util/project-id.ts): `src/util/project-id.ts`
- [Intelligence Contracts](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/contracts.ts): `src/intelligence/contracts.ts`
- [Evidence Provenance](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/evidence.ts): `src/intelligence/evidence.ts`

### Intelligence

- [Relationship Graph](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/graph/graph-engine.ts): `src/intelligence/graph/graph-engine.ts`
- [Search](https://github.com/backbencher-hq/backbencher-brain/tree/main/src/intelligence/search): `src/intelligence/search`
- [Semantic Retrieval](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/brain/semantic/engine.ts): `src/brain/semantic/engine.ts`
- [Health and Freshness](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/health/health-provider.ts): `src/intelligence/health/health-provider.ts`
- [Visualization](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/visualization/visualization-engine.ts): `src/intelligence/visualization/visualization-engine.ts`

### Analysis and Maintenance

- [Code Editing](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/edit/edit-engine.ts): `src/intelligence/edit/edit-engine.ts`
- [Security Analysis](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/security/rebuild/engine.ts): `src/intelligence/security/rebuild/engine.ts`
- [Pattern Analysis](https://github.com/backbencher-hq/backbencher-brain/blob/main/src/intelligence/patterns/orphans.ts): `src/intelligence/patterns/orphans.ts`
- [Migration](https://github.com/backbencher-hq/backbencher-brain/tree/main/src/intelligence/migration): `src/intelligence/migration`

### Other components

- **Repository User**

## Connections

- Repository User → CLI: runs commands (evidence: `README.md`)
- Repository User → MCP Server: connects host (evidence: `README.md`)
- Repository User → LSP Server: uses editor (evidence: `README.md`)
- CLI → Parallel Indexer: indexes project (evidence: `src/cli/index.ts`)
- Parallel Indexer → Language Detection: detects languages
- Parallel Indexer → AST Engine: parses files
- AST Engine → Tree-sitter Grammars: uses parsers (evidence: `README.md`)
- Parallel Indexer → Project Database: stores index (evidence: `README.md`)
- CLI → Project Database: opens index (evidence: `src/cli/index.ts`)
- MCP Server → Project Identity: resolves project (evidence: `src/mcp/server.ts`)
- MCP Server → Project Database: checks index (evidence: `src/mcp/server.ts`)
- MCP Server → Tool Registry: registers tools (evidence: `src/mcp/server.ts`)
- LSP Server → Project Database: opens index (evidence: `src/lsp/server.ts`)
- LSP Server → Project Identity: resolves project (evidence: `src/lsp/server.ts`)
- Project Database → Project Identity: resolves data path (evidence: `src/brain/database.ts`)
- CLI → Relationship Graph: queries relationships
- CLI → Search: searches index (evidence: `README.md`)
- CLI → Health and Freshness: reports health (evidence: `src/cli/index.ts`)
- CLI → Semantic Retrieval: requests embeddings (evidence: `src/cli/index.ts`)
- Project Database → Relationship Graph: supplies index rows (evidence: `src/intelligence/graph/graph-engine.ts`)
- Project Database → Visualization: supplies index rows (evidence: `src/intelligence/visualization/visualization-engine.ts`)
- Project Database → Health and Freshness: supplies index state (evidence: `src/intelligence/health/health-provider.ts`)
- Project Database → Pattern Analysis: supplies index rows (evidence: `src/intelligence/patterns/orphans.ts`)
- Project Database → Semantic Retrieval: stores embeddings (evidence: `src/brain/semantic/engine.ts`)
- Semantic Retrieval → Intelligence Contracts: returns answers
- Relationship Graph → Intelligence Contracts: returns relationships (evidence: `src/intelligence/graph/graph-engine.ts`)
- Intelligence Contracts → Evidence Provenance: carries provenance (evidence: `src/intelligence/contracts.ts`)
- CLI → Visualization: renders index (evidence: `README.md`)
- CLI → Code Editing: edits source (evidence: `README.md`)
- CLI → Security Analysis: analyzes security (evidence: `README.md`)
- CLI → Pattern Analysis: finds patterns (evidence: `README.md`)
- CLI → Migration: migrates code (evidence: `README.md`)
