# colbymchenry/codegraph architecture

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

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

## Overview

#### Purpose and entry points
CodeGraph is a local semantic-code-intelligence system for AI agents and CLI users. It indexes a project into a SQLite knowledge graph, resolves cross-file and framework relationships, and serves focused source/context, call paths, and impact analysis. Main CLI dispatch is `src/bin/codegraph.ts`; embeddable API exports originate at `src/index.ts`. Agent integration runs through the MCP server in `src/mcp/index.ts`.

#### 1. CLI lifecycle and project boundary
The CLI owns project commands (`init`, `index`, `sync`, query/explore, daemon, install, upgrade) and supervises fatal errors and runtime checks. A project’s durable boundary is its local `.codegraph/` directory/database, with configuration loaded from project-root conventions. Installation is a separate concern: it writes MCP configuration/instructions for supported agent hosts.
Paths: `src/bin/codegraph.ts`, `src/project-config.ts`, `src/installer/index.ts`.

#### 2. Extraction pipeline
Indexing discovers eligible source files, selects language extractors, parses them through Tree-sitter or the native kernel, and emits structural nodes and raw relationships. Extraction supports worker-based parsing/storage so full indexing can parallelize while writes are coordinated. Composite/template languages have dedicated extractors alongside per-language implementations.
Paths: `src/extraction/index.ts`, `src/extraction/parse-pool.ts`, `src/extraction/store-writer.ts`.

#### 3. Rust kernel / portable parser boundary
The Rust crate is the high-performance extraction backend for a large subset of languages. TypeScript loads its compiled artifact, decodes kernel output, and falls back to portable WASM Tree-sitter parsing when unavailable or unsuitable per file. This boundary preserves a common graph shape regardless of parsing engine.
Paths: `codegraph-kernel/src/lib.rs`, `src/extraction/kernel/loader.ts`, `src/extraction/kernel/decode.ts`.

#### 4. Persistent graph and search
SQLite is the system of record for files, symbols, edges, and FTS-backed retrieval. The DB layer encapsulates schema/migrations and query operations; WAL handling is explicitly managed to keep reads available during sync. Higher-level graph traversal and query modules operate on this persisted representation rather than source files directly.
Paths: `src/db/schema.sql`, `src/db/index.ts`, `src/graph/traversal.ts`.

#### 5. Resolution and synthesized relationships
After extraction, resolution maps imports, references, calls, aliases, and workspace/module relationships to graph entities. Worker pools and caches control CPU/memory use. Framework resolvers and specialized synthesizers add relationships static syntax alone cannot express—routes, callbacks, dispatch, Swift/ObjC bridging, React Native, and similar conventions—marking heuristic edges distinctly.
Paths: `src/resolution/index.ts`, `src/resolution/resolver-pool.ts`, `src/resolution/frameworks/index.ts`.

#### 6. Query/context serving
Graph queries power symbol search, caller/callee traversal, impact analysis, and ranked context construction. The context layer formats selected source and relationships into agent-facing output. MCP exposes this primarily as an `explore` workflow, with request/session orchestration isolated from graph execution.
Paths: `src/graph/queries.ts`, `src/context/index.ts`, `src/mcp/engine.ts`.

#### 7. MCP daemon and continuous synchronization
MCP runs over stdio but can attach sessions to a per-project background daemon. Startup performs handshake/catch-up; query workers isolate concurrent requests. Native file watching applies debounced incremental sync and tracks pending edits so responses can signal staleness rather than silently serving outdated graph data.
Paths: `src/mcp/daemon.ts`, `src/mcp/session.ts`, `src/sync/watcher.ts`.

#### Runtime, infrastructure, and external boundaries
Core runtime is TypeScript/Node; the library API requires modern Node SQLite support, while distributed CLI builds bundle Node. Rust provides the native kernel; Tree-sitter WASM assets provide portable parsing. Storage and indexing are local SQLite only. Optional anonymous telemetry is aggregated locally then sent to a Cloudflare Worker endpoint; the product graph itself does not require external services.
Paths: `package.json`, `codegraph-kernel/Cargo.toml`, `telemetry-worker/src/index.ts`.

Main entry points: [`src/db/index.ts`](https://github.com/colbymchenry/codegraph/blob/main/src/db/index.ts) (SQLite knowledge graph), [`src/extraction/index.ts`](https://github.com/colbymchenry/codegraph/blob/main/src/extraction/index.ts) (Extraction coordinator), [`src/bin/codegraph.ts`](https://github.com/colbymchenry/codegraph/blob/main/src/bin/codegraph.ts) (CLI dispatcher), [`src/extraction/kernel/loader.ts`](https://github.com/colbymchenry/codegraph/blob/main/src/extraction/kernel/loader.ts) (Kernel loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI dispatcher<br/>TypeScript CLI<br/>[codegraph.ts]"]
  node_project_config["Project configuration<br/>project boundary<br/>[project-config.ts]"]
  node_installer["Agent host installer<br/>installation<br/>[index.ts]"]
  node_api["Embeddable API<br/>TypeScript API<br/>[index.ts]"]
end

subgraph group_indexing["Indexing pipeline"]
  node_extraction["Extraction coordinator<br/>indexing orchestration<br/>[index.ts]"]
  node_parse_pool["Parse worker pool<br/>parallel parser<br/>[parse-pool.ts]"]
  node_store_writer["Coordinated graph writer<br/>storage writer<br/>[store-writer.ts]"]
  node_kernel_loader["Kernel loader<br/>parser selector<br/>[loader.ts]"]
  node_kernel_decode["Kernel output decoder<br/>parser adapter<br/>[decode.ts]"]
  node_resolver["Relationship resolution<br/>resolution pipeline<br/>[index.ts]"]
  node_resolver_pool["Resolver worker pool<br/>parallel resolver<br/>[resolver-pool.ts]"]
  node_frameworks["Framework synthesizers<br/>heuristic resolver<br/>[index.ts]"]
end

subgraph group_graph["Persistent graph"]
  node_sqlite[("SQLite knowledge graph<br/>local system of record<br/>[index.ts]")]
  node_schema["SQLite schema and migrations<br/>database schema<br/>[schema.sql]"]
  node_traversal["Graph traversal<br/>graph service<br/>[traversal.ts]"]
end

subgraph group_serving["Query and MCP"]
  node_queries["Graph queries<br/>query service<br/>[queries.ts]"]
  node_context["Context builder<br/>agent output<br/>[index.ts]"]
  node_mcp_engine["MCP explore engine<br/>MCP execution<br/>[engine.ts]"]
  node_mcp_daemon["MCP daemon<br/>background service<br/>[daemon.ts]"]
  node_mcp_session["MCP session<br/>session orchestration<br/>[session.ts]"]
  node_watcher["Incremental sync watcher<br/>file synchronization<br/>[watcher.ts]"]
end

subgraph group_runtime["Runtime boundaries"]
  node_rust_kernel{{"Rust extraction kernel<br/>native parser<br/>[lib.rs]"}}
  node_portable_parser{{"Tree-sitter WASM<br/>portable parser"}}
  node_telemetry{{"Telemetry worker<br/>optional external endpoint<br/>[index.ts]"}}
end

node_cli -->|"loads"| node_project_config
node_cli -->|"runs index/sync"| node_extraction
node_cli -->|"runs install"| node_installer
node_api -->|"embeds"| node_extraction
node_extraction -->|"dispatches files"| node_parse_pool
node_parse_pool -->|"parses through"| node_kernel_loader
node_kernel_loader -->|"uses when supported"| node_rust_kernel
node_kernel_loader -.->|"falls back to"| node_portable_parser
node_rust_kernel -->|"emits native output"| node_kernel_decode
node_kernel_decode -->|"normalizes graph data"| node_store_writer
node_portable_parser -->|"emits common graph data"| node_store_writer
node_store_writer -->|"writes nodes and raw edges"| node_sqlite
node_sqlite -->|"uses"| node_schema
node_extraction -->|"runs after extraction"| node_resolver
node_resolver -->|"parallelizes"| node_resolver_pool
node_resolver_pool -->|"applies conventions"| node_frameworks
node_resolver -->|"resolves persisted entities"| node_sqlite
node_frameworks -.->|"writes heuristic edges"| node_sqlite
node_sqlite -->|"provides graph"| node_traversal
node_traversal -->|"supports"| node_queries
node_queries -->|"selects ranked results"| node_context
node_mcp_engine -->|"executes explore"| node_queries
node_mcp_engine -->|"returns context"| node_context
node_mcp_session -->|"attaches to"| node_mcp_daemon
node_mcp_session -->|"routes requests"| node_mcp_engine
node_mcp_daemon -->|"runs continuous sync"| node_watcher
node_watcher -->|"triggers incremental index"| node_extraction
node_telemetry -.->|"does not access product graph"| node_sqlite

click node_cli "https://github.com/colbymchenry/codegraph/blob/main/src/bin/codegraph.ts"
click node_project_config "https://github.com/colbymchenry/codegraph/blob/main/src/project-config.ts"
click node_installer "https://github.com/colbymchenry/codegraph/blob/main/src/installer/index.ts"
click node_api "https://github.com/colbymchenry/codegraph/blob/main/src/index.ts"
click node_extraction "https://github.com/colbymchenry/codegraph/blob/main/src/extraction/index.ts"
click node_parse_pool "https://github.com/colbymchenry/codegraph/blob/main/src/extraction/parse-pool.ts"
click node_store_writer "https://github.com/colbymchenry/codegraph/blob/main/src/extraction/store-writer.ts"
click node_kernel_loader "https://github.com/colbymchenry/codegraph/blob/main/src/extraction/kernel/loader.ts"
click node_kernel_decode "https://github.com/colbymchenry/codegraph/blob/main/src/extraction/kernel/decode.ts"
click node_rust_kernel "https://github.com/colbymchenry/codegraph/blob/main/codegraph-kernel/src/lib.rs"
click node_resolver "https://github.com/colbymchenry/codegraph/blob/main/src/resolution/index.ts"
click node_resolver_pool "https://github.com/colbymchenry/codegraph/blob/main/src/resolution/resolver-pool.ts"
click node_frameworks "https://github.com/colbymchenry/codegraph/blob/main/src/resolution/frameworks/index.ts"
click node_sqlite "https://github.com/colbymchenry/codegraph/blob/main/src/db/index.ts"
click node_schema "https://github.com/colbymchenry/codegraph/blob/main/src/db/schema.sql"
click node_traversal "https://github.com/colbymchenry/codegraph/blob/main/src/graph/traversal.ts"
click node_queries "https://github.com/colbymchenry/codegraph/blob/main/src/graph/queries.ts"
click node_context "https://github.com/colbymchenry/codegraph/blob/main/src/context/index.ts"
click node_mcp_engine "https://github.com/colbymchenry/codegraph/blob/main/src/mcp/engine.ts"
click node_mcp_daemon "https://github.com/colbymchenry/codegraph/blob/main/src/mcp/daemon.ts"
click node_mcp_session "https://github.com/colbymchenry/codegraph/blob/main/src/mcp/session.ts"
click node_watcher "https://github.com/colbymchenry/codegraph/blob/main/src/sync/watcher.ts"
click node_telemetry "https://github.com/colbymchenry/codegraph/blob/main/telemetry-worker/src/index.ts"

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_project_config,node_installer,node_api toneBlue
class node_extraction,node_parse_pool,node_store_writer,node_kernel_loader,node_kernel_decode,node_resolver,node_resolver_pool,node_frameworks toneAmber
class node_sqlite,node_schema,node_traversal toneMint
class node_queries,node_context,node_mcp_engine,node_mcp_daemon,node_mcp_session,node_watcher toneRose
class node_rust_kernel,node_portable_parser,node_telemetry toneIndigo
```

## Components

### Entry points

- [CLI dispatcher](https://github.com/colbymchenry/codegraph/blob/main/src/bin/codegraph.ts): TypeScript CLI · Owns project commands and runtime supervision. · `src/bin/codegraph.ts`
- [Project configuration](https://github.com/colbymchenry/codegraph/blob/main/src/project-config.ts): project boundary · Loads root conventions and the local durable project state. · `src/project-config.ts`
- [Agent host installer](https://github.com/colbymchenry/codegraph/blob/main/src/installer/index.ts): installation · Writes MCP configuration and instructions for supported hosts. · `src/installer/index.ts`
- [Embeddable API](https://github.com/colbymchenry/codegraph/blob/main/src/index.ts): TypeScript API · `src/index.ts`

### Indexing pipeline

- [Extraction coordinator](https://github.com/colbymchenry/codegraph/blob/main/src/extraction/index.ts): indexing orchestration · Discovers files, selects extractors, and emits structural graph data. · `src/extraction/index.ts`
- [Parse worker pool](https://github.com/colbymchenry/codegraph/blob/main/src/extraction/parse-pool.ts): parallel parser · Parallelizes eligible file parsing. · `src/extraction/parse-pool.ts`
- [Coordinated graph writer](https://github.com/colbymchenry/codegraph/blob/main/src/extraction/store-writer.ts): storage writer · Coordinates indexing writes from worker-based extraction. · `src/extraction/store-writer.ts`
- [Kernel loader](https://github.com/colbymchenry/codegraph/blob/main/src/extraction/kernel/loader.ts): parser selector · Chooses native kernel output or portable parsing per file. · `src/extraction/kernel/loader.ts`
- [Kernel output decoder](https://github.com/colbymchenry/codegraph/blob/main/src/extraction/kernel/decode.ts): parser adapter · Converts native output into the common graph shape. · `src/extraction/kernel/decode.ts`
- [Relationship resolution](https://github.com/colbymchenry/codegraph/blob/main/src/resolution/index.ts): resolution pipeline · Maps raw syntax relationships to graph entities. · `src/resolution/index.ts`
- [Resolver worker pool](https://github.com/colbymchenry/codegraph/blob/main/src/resolution/resolver-pool.ts): parallel resolver · Controls CPU and memory during resolution. · `src/resolution/resolver-pool.ts`
- [Framework synthesizers](https://github.com/colbymchenry/codegraph/blob/main/src/resolution/frameworks/index.ts): heuristic resolver · Adds convention-based edges such as routes and callbacks. · `src/resolution/frameworks/index.ts`

### Persistent graph

- [SQLite knowledge graph](https://github.com/colbymchenry/codegraph/blob/main/src/db/index.ts): local system of record · Stores files, symbols, edges, and FTS retrieval data. · `src/db/index.ts`
- [SQLite schema and migrations](https://github.com/colbymchenry/codegraph/blob/main/src/db/schema.sql): database schema · Defines persisted graph and search structures. · `src/db/schema.sql`
- [Graph traversal](https://github.com/colbymchenry/codegraph/blob/main/src/graph/traversal.ts): graph service · Traverses the persisted graph rather than source files. · `src/graph/traversal.ts`

### Query and MCP

- [Graph queries](https://github.com/colbymchenry/codegraph/blob/main/src/graph/queries.ts): query service · Provides search, call paths, and impact analysis. · `src/graph/queries.ts`
- [Context builder](https://github.com/colbymchenry/codegraph/blob/main/src/context/index.ts): agent output · Ranks and formats source and relationships into focused context. · `src/context/index.ts`
- [MCP explore engine](https://github.com/colbymchenry/codegraph/blob/main/src/mcp/engine.ts): MCP execution · Isolates request orchestration from graph execution. · `src/mcp/engine.ts`
- [MCP daemon](https://github.com/colbymchenry/codegraph/blob/main/src/mcp/daemon.ts): background service · Attaches project sessions and performs startup catch-up. · `src/mcp/daemon.ts`
- [MCP session](https://github.com/colbymchenry/codegraph/blob/main/src/mcp/session.ts): session orchestration · Coordinates stdio sessions and daemon attachment. · `src/mcp/session.ts`
- [Incremental sync watcher](https://github.com/colbymchenry/codegraph/blob/main/src/sync/watcher.ts): file synchronization · Debounces edits and records staleness during incremental sync. · `src/sync/watcher.ts`

### Runtime boundaries

- [Rust extraction kernel](https://github.com/colbymchenry/codegraph/blob/main/codegraph-kernel/src/lib.rs): native parser · High-performance backend for a large language subset. · `codegraph-kernel/src/lib.rs`
- **Tree-sitter WASM**: portable parser · Fallback parser when the native kernel is unavailable or unsuitable.
- [Telemetry worker](https://github.com/colbymchenry/codegraph/blob/main/telemetry-worker/src/index.ts): optional external endpoint · Receives aggregated anonymous telemetry only. · `telemetry-worker/src/index.ts`

## Connections

- CLI dispatcher → Project configuration: loads
- CLI dispatcher → Extraction coordinator: runs index/sync
- CLI dispatcher → Agent host installer: runs install
- Embeddable API → Extraction coordinator: embeds
- Extraction coordinator → Parse worker pool: dispatches files
- Parse worker pool → Kernel loader: parses through
- Kernel loader → Rust extraction kernel: uses when supported
- Kernel loader → Tree-sitter WASM: falls back to
- Rust extraction kernel → Kernel output decoder: emits native output
- Kernel output decoder → Coordinated graph writer: normalizes graph data
- Tree-sitter WASM → Coordinated graph writer: emits common graph data
- Coordinated graph writer → SQLite knowledge graph: writes nodes and raw edges
- SQLite knowledge graph → SQLite schema and migrations: uses
- Extraction coordinator → Relationship resolution: runs after extraction
- Relationship resolution → Resolver worker pool: parallelizes
- Resolver worker pool → Framework synthesizers: applies conventions
- Relationship resolution → SQLite knowledge graph: resolves persisted entities
- Framework synthesizers → SQLite knowledge graph: writes heuristic edges
- SQLite knowledge graph → Graph traversal: provides graph
- Graph traversal → Graph queries: supports
- Graph queries → Context builder: selects ranked results
- MCP explore engine → Graph queries: executes explore
- MCP explore engine → Context builder: returns context
- MCP session → MCP daemon: attaches to
- MCP session → MCP explore engine: routes requests
- MCP daemon → Incremental sync watcher: runs continuous sync
- Incremental sync watcher → Extraction coordinator: triggers incremental index
- Telemetry worker → SQLite knowledge graph: does not access product graph
