# unknownswordsman/codegraph architecture

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

- Interactive diagram: https://gitdiagram.com/unknownswordsman/codegraph
- Repository: https://github.com/unknownswordsman/codegraph

## Overview

1. **What this repo is**
   - CodeGraph is a TypeScript/Node-based CLI plus embeddable library that builds a local code knowledge graph for a project.
   - The core product boundary is the per-project `.codegraph/` directory, which holds the SQLite index and metadata; everything else orchestrates how that index is built, queried, kept fresh, and exposed to AI agents.

2. **Top-level runtime split**
   - There are two execution modes:
     - **Bundled CLI/runtime** for end users (`src/bin`, install scripts, bundle scripts).
     - **Library/API mode** for embedding in another Node 22.5+ process (`src/index.ts` and exports from the package entrypoint).
   - The CLI is what agents and users interact with; the library is the same engine used programmatically.

3. **Indexing pipeline**
   - The indexing flow lives mainly under `src/extraction`, `src/resolution`, `src/graph`, and `src/db`.
   - Source files are parsed with **tree-sitter**, language-specific extractors identify symbols/edges, then a resolution pass connects references across files, imports, call sites, inheritance, and framework conventions.
   - The result is stored in **SQLite** with **FTS5** for search.

4. **Storage boundary**
   - `src/db` defines schema, migrations, and query helpers for the on-disk graph database.
   - The repository uses SQLite as the single source of truth; the architecture is intentionally local-first and does not depend on a remote indexing service.
   - Tests around reopen/locking/performance indicate the DB layer is tuned for concurrent read-heavy access and resilience to file replacement.

5. **Graph and query subsystem**
   - `src/graph` and `src/search` provide read/query primitives over the indexed data: symbol lookup, callers/callees, impact radius, and search parsing.
   - `src/context` builds “agent-ready” context bundles from the graph: ranked symbols, formatted snippets, and boundary markers used to answer questions directly.
   - This is the main data-serving layer once indexing is complete.

6. **Resolution and cross-language synthesis**
   - `src/resolution` is where CodeGraph becomes more than syntax extraction.
   - It contains framework resolvers, import resolution, path aliases, workspace package handling, and synthetic edge generators for hard-to-follow flows such as callbacks, dispatch systems, Swift/ObjC bridging, React Native bridges, Expo modules, and framework-specific route conventions.
   - These heuristics are a major architectural boundary because they close gaps that raw AST parsing cannot.

7. **Language frontends**
   - `src/extraction/languages` contains per-language extractors for TypeScript/JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C/C++, Swift, Kotlin, Scala, Dart, Lua/Luau, R, Liquid, Pascal/Delphi, and several frontend frameworks.
   - Some extra file-format extractors exist alongside the language layer, such as Astro, Svelte, Vue, Liquid, Razor, MyBatis, and DFM-like forms.
   - The extractors are modular, which makes language support an additive subsystem rather than a monolith.

8. **MCP server architecture**
   - `src/mcp` implements the server that AI agents actually talk to.
   - It exposes the CodeGraph query surface through MCP, manages session lifecycle, transport, query workers, daemon/shared-process behavior, and watchdogs for liveness and parent-process death.
   - This layer is the boundary between agent tool calls and the local graph database.

9. **Freshness and syncing**
   - `src/sync` handles watch-based incremental updates using native file-system events, debounce policy, git-hook support, and worktree awareness.
   - The architecture favors “always fresh” indexes: change detection feeds incremental resyncs, and stale-file safeguards are surfaced to the agent when the graph may lag behind the working tree.
   - This is important because the agent-facing answers depend on the current project state, not a stale snapshot.

10. **Installer and agent integration**
    - `src/installer` and `scripts/add-lang` / `install.sh` / `install.ps1` are the operational layer that wires CodeGraph into external agents and user machines.
    - The installer detects supported agents, writes their MCP configuration, and optionally injects instructions into agent-specific guidance files.
    - This is the integration boundary to Claude Code, Cursor, Codex, opencode, Gemini, Antigravity, Kiro, and Hermes.

11. **Telemetry and external service boundary**
    - `src/telemetry` collects anonymous usage data, while `telemetry-worker/` hosts the ingestion endpoint as a separate deployable service.
    - The architecture keeps code-content and file/path data local; telemetry is limited to aggregated usage metadata.
    - In contrast to the core product, telemetry is the only clearly separate cloud-facing subsystem in the repo.

12. **Distribution, website, and validation**
    - `site/` is an Astro documentation/marketing site published via GitHub Pages workflows.
    - `scripts/` contains release, packaging, benchmark, and evaluation tooling; this repo treats release engineering and agent-eval experiments as first-class operational concerns.
    - `__tests__` is extensive and maps directly onto the major boundaries above, especially extraction, resolution, daemon/watch behavior, MCP behavior, installer behavior, and SQLite persistence.

13. **End-to-end data flow**
    - A user initializes a project → the CLI scans source files → extractors build symbols and raw edges → resolvers add cross-file/framework/bridge links → SQLite stores the graph → MCP queries read from that graph → watch/sync keeps it current as files change.
    - The same graph also powers CLI commands like search, callers/callees, impact analysis, and affected-test detection.

14. **Primary architectural shape**
    - This repo is best understood as a local indexing engine with three outer shells:
      - **Build shell:** extraction + resolution + storage.
      - **Serve shell:** CLI + MCP + query/context APIs.
      - **Operate shell:** installer, watcher/sync, telemetry, packaging, and docs.
    - The center of gravity is the project-local SQLite graph; everything else exists to populate it, keep it fresh, or expose it to agents.

Main entry points: [`src/graph/index.ts`](https://github.com/unknownswordsman/codegraph/blob/main/src/graph/index.ts) (Graph API), [`src/mcp/index.ts`](https://github.com/unknownswordsman/codegraph/blob/main/src/mcp/index.ts) (MCP server), [`src/extraction/index.ts`](https://github.com/unknownswordsman/codegraph/blob/main/src/extraction/index.ts) (Extractors), [`src/bin/codegraph.ts`](https://github.com/unknownswordsman/codegraph/blob/main/src/bin/codegraph.ts) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build shell"]
  node_extractor["Extractors<br/>parse frontends<br/>[index.ts]"]
  node_languages["Languages<br/>language plugins<br/>[index.ts]"]
  node_resolve["Resolution<br/>cross-file linking<br/>[index.ts]"]
  node_frameworks["Framework rules<br/>resolver plugins<br/>[index.ts]"]
  node_db[("SQLite DB<br/>local graph store<br/>[index.ts]")]
end

subgraph group_serve["Serve shell"]
  node_cli["CLI<br/>runtime entry<br/>[codegraph.ts]"]
  node_library["Library API<br/>package entry<br/>[index.ts]"]
  node_graph["Graph API<br/>query layer<br/>[index.ts]"]
  node_search["Search parser<br/>query parsing<br/>[query-parser.ts]"]
  node_context["Context builder<br/>agent context<br/>[index.ts]"]
  node_mcp["MCP server<br/>agent server<br/>[index.ts]"]
end

subgraph group_operate["Operate shell"]
  node_sync["Sync watcher<br/>freshness<br/>[index.ts]"]
  node_installer["Installer<br/>agent integration<br/>[index.ts]"]
  node_telemetry["Telemetry<br/>usage signals<br/>[index.ts]"]
  node_reasoning["Reasoning<br/>login/config<br/>[reasoner.ts]"]
  node_upgrade["Upgrade<br/>versioning<br/>[index.ts]"]
  node_site["Docs site<br/>documentation site<br/>[index.astro]"]
  node_telemetry_worker["Telemetry worker<br/>cloud service<br/>[index.ts]"]
end

node_cli -->|"indexes"| node_extractor
node_extractor -->|"delegates"| node_languages
node_extractor -->|"raw edges"| node_resolve
node_resolve -->|"applies"| node_frameworks
node_resolve -->|"stores"| node_db
node_db -->|"reads"| node_graph
node_graph -->|"parses"| node_search
node_graph -->|"feeds"| node_context
node_mcp -->|"serves"| node_graph
node_mcp -->|"formats"| node_context
node_cli -->|"hosts"| node_mcp
node_sync -->|"refreshes"| node_db
node_sync -->|"signals"| node_mcp
node_installer -->|"configures"| node_mcp
node_installer -->|"installs"| node_cli
node_telemetry -->|"reports"| node_telemetry_worker
node_library -->|"embeds"| node_extractor
node_library -->|"queries"| node_graph
node_upgrade -.->|"supports"| node_cli
node_site -.->|"documents"| node_installer
node_site -.->|"explains"| node_graph

click node_cli "https://github.com/unknownswordsman/codegraph/blob/main/src/bin/codegraph.ts"
click node_library "https://github.com/unknownswordsman/codegraph/blob/main/src/index.ts"
click node_extractor "https://github.com/unknownswordsman/codegraph/blob/main/src/extraction/index.ts"
click node_languages "https://github.com/unknownswordsman/codegraph/blob/main/src/extraction/languages/index.ts"
click node_resolve "https://github.com/unknownswordsman/codegraph/blob/main/src/resolution/index.ts"
click node_frameworks "https://github.com/unknownswordsman/codegraph/blob/main/src/resolution/frameworks/index.ts"
click node_db "https://github.com/unknownswordsman/codegraph/blob/main/src/db/index.ts"
click node_graph "https://github.com/unknownswordsman/codegraph/blob/main/src/graph/index.ts"
click node_search "https://github.com/unknownswordsman/codegraph/blob/main/src/search/query-parser.ts"
click node_context "https://github.com/unknownswordsman/codegraph/blob/main/src/context/index.ts"
click node_mcp "https://github.com/unknownswordsman/codegraph/blob/main/src/mcp/index.ts"
click node_sync "https://github.com/unknownswordsman/codegraph/blob/main/src/sync/index.ts"
click node_installer "https://github.com/unknownswordsman/codegraph/blob/main/src/installer/index.ts"
click node_telemetry "https://github.com/unknownswordsman/codegraph/blob/main/src/telemetry/index.ts"
click node_reasoning "https://github.com/unknownswordsman/codegraph/blob/main/src/reasoning/reasoner.ts"
click node_upgrade "https://github.com/unknownswordsman/codegraph/blob/main/src/upgrade/index.ts"
click node_site "https://github.com/unknownswordsman/codegraph/blob/main/site/src/pages/index.astro"
click node_telemetry_worker "https://github.com/unknownswordsman/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_extractor,node_languages,node_resolve,node_frameworks,node_db toneBlue
class node_cli,node_library,node_graph,node_search,node_context,node_mcp toneAmber
class node_sync,node_installer,node_telemetry,node_reasoning,node_upgrade,node_site,node_telemetry_worker toneMint
```

## Components

### Build shell

Extraction, resolution, and SQLite indexing pipeline.

- [Extractors](https://github.com/unknownswordsman/codegraph/blob/main/src/extraction/index.ts): parse frontends · Tree-sitter and language-specific symbol/edge extraction. · `src/extraction/index.ts`
- [Languages](https://github.com/unknownswordsman/codegraph/blob/main/src/extraction/languages/index.ts): language plugins · Per-language and file-format extractors for supported syntaxes. · `src/extraction/languages/index.ts`
- [Resolution](https://github.com/unknownswordsman/codegraph/blob/main/src/resolution/index.ts): cross-file linking · Import, alias, framework, and synthetic edge resolution. · `src/resolution/index.ts`
- [Framework rules](https://github.com/unknownswordsman/codegraph/blob/main/src/resolution/frameworks/index.ts): resolver plugins · Framework-specific heuristics for routes, dispatch, and bridges. · `src/resolution/frameworks/index.ts`
- [SQLite DB](https://github.com/unknownswordsman/codegraph/blob/main/src/db/index.ts): local graph store · On-disk project database with schema, migrations, and query helpers. · `src/db/index.ts`

### Serve shell

CLI, MCP server, graph queries, and agent-facing context.

- [CLI](https://github.com/unknownswordsman/codegraph/blob/main/src/bin/codegraph.ts): runtime entry · Bundled command-line entrypoint and process supervision. · `src/bin/codegraph.ts`
- [Library API](https://github.com/unknownswordsman/codegraph/blob/main/src/index.ts): package entry · Embeddable Node API surface for programmatic use. · `src/index.ts`
- [Graph API](https://github.com/unknownswordsman/codegraph/blob/main/src/graph/index.ts): query layer · Symbol lookup, traversal, callers/callees, and impact analysis. · `src/graph/index.ts`
- [Search parser](https://github.com/unknownswordsman/codegraph/blob/main/src/search/query-parser.ts): query parsing · Search query syntax and parsing utilities over indexed content. · `src/search/query-parser.ts`
- [Context builder](https://github.com/unknownswordsman/codegraph/blob/main/src/context/index.ts): agent context · Ranks symbols and formats snippets into answer-ready bundles. · `src/context/index.ts`
- [MCP server](https://github.com/unknownswordsman/codegraph/blob/main/src/mcp/index.ts): agent server · Agent-facing server, session management, workers, and transport. · `src/mcp/index.ts`

### Operate shell

Freshness, installation, telemetry, packaging, and docs.

- [Sync watcher](https://github.com/unknownswordsman/codegraph/blob/main/src/sync/index.ts): freshness · File watching, debounce, git-hook, and worktree-aware incremental resync. · `src/sync/index.ts`
- [Installer](https://github.com/unknownswordsman/codegraph/blob/main/src/installer/index.ts): agent integration · Configures external agents and writes MCP integration settings. · `src/installer/index.ts`
- [Telemetry](https://github.com/unknownswordsman/codegraph/blob/main/src/telemetry/index.ts): usage signals · Anonymous usage collection and client-side telemetry hooks. · `src/telemetry/index.ts`
- [Reasoning](https://github.com/unknownswordsman/codegraph/blob/main/src/reasoning/reasoner.ts): login/config · Support for user configuration, credentials, and reasoning workflows. · `src/reasoning/reasoner.ts`
- [Upgrade](https://github.com/unknownswordsman/codegraph/blob/main/src/upgrade/index.ts): versioning · Upgrade and compatibility flows for installed environments. · `src/upgrade/index.ts`
- [Docs site](https://github.com/unknownswordsman/codegraph/blob/main/site/src/pages/index.astro): documentation site · Astro documentation and marketing site. · `site/src/pages/index.astro`
- [Telemetry worker](https://github.com/unknownswordsman/codegraph/blob/main/telemetry-worker/src/index.ts): cloud service · Separate deployable ingestion endpoint for telemetry. · `telemetry-worker/src/index.ts`

## Connections

- CLI → Extractors: indexes · CLI drives project scanning and extraction.
- Extractors → Languages: delegates · Shared extraction core dispatches to per-language frontends.
- Extractors → Resolution: raw edges · Extraction outputs symbols and unresolved relationships into resolution.
- Resolution → Framework rules: applies · Framework resolvers add synthetic and convention-based links.
- Resolution → SQLite DB: stores · Resolved graph is persisted in SQLite.
- SQLite DB → Graph API: reads · Graph queries are served from the project-local database.
- Graph API → Search parser: parses · Search layer interprets user query syntax.
- Graph API → Context builder: feeds · Query results become agent-ready context bundles.
- MCP server → Graph API: serves · MCP exposes graph queries to external agents.
- MCP server → Context builder: formats · Agent responses are assembled from graph context.
- CLI → MCP server: hosts · CLI starts and supervises MCP sessions and transports.
- Sync watcher → SQLite DB: refreshes · File-system changes trigger incremental graph updates.
- Sync watcher → MCP server: signals · Staleness and catch-up state affect agent-facing behavior.
- Installer → MCP server: configures · Installer writes agent configuration for MCP access.
- Installer → CLI: installs · Operational scripts wire the CLI into user environments.
- Telemetry → Telemetry worker: reports · Client telemetry is sent to the separate ingestion service.
- Library API → Extractors: embeds · Programmatic API uses the same indexing engine.
- Library API → Graph API: queries · Library consumers can read the graph directly.
- Upgrade → CLI: supports · Upgrade flow keeps installed CLI/runtime compatible.
- Docs site → Installer: documents · Docs site explains installation and integrations.
- Docs site → Graph API: explains · Documentation covers core graph concepts and queries.