# https://github.com/CodeGraphContext/CodeGraphContext Project Manual Generated at: 2026-07-05 23:32:51 UTC ## Table of Contents - [Overview & System Architecture](#page-1) - [CLI Toolkit, MCP Server & VS Code Extension](#page-2) - [Language Parsers & Indexing Pipeline](#page-3) - [Database Backends, Data Model, Bundles & Visualization](#page-4) ## Overview & System Architecture ### Related Pages Related topics: [CLI Toolkit, MCP Server & VS Code Extension](#page-2), [Language Parsers & Indexing Pipeline](#page-3), [Database Backends, Data Model, Bundles & Visualization](#page-4)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/README.md) - [docs/docs/concepts/architecture.md](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/docs/docs/concepts/architecture.md) - [docs/docs/concepts/how-it-works.md](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/docs/docs/concepts/how-it-works.md) - [docs/docs/index.md](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/docs/docs/index.md) - [pyproject.toml](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/pyproject.toml) - [src/codegraphcontext/__init__.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/__init__.py) - [src/codegraphcontext/cli.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli.py) - [src/codegraphcontext/core/database.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/core/database.py) - [src/codegraphcontext/core/database_kuzu.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/core/database_kuzu.py) - [src/codegraphcontext/parsers/factory.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/parsers/factory.py)
# Overview & System Architecture CodeGraphContext (CGC) is an MCP-native code intelligence tool that converts source code into a traversable property graph and exposes graph queries to AI agents. Its purpose is to give large language models accurate, structural awareness of real codebases so they can answer questions, refactor safely, and analyze complexity without hallucinating symbols or relationships. Source: [README.md:1-30]() The project is positioned as a bridge between a static analysis layer (Tree-sitter parsers) and a runtime query layer (graph database + MCP server). The intent is that any AI client compatible with the Model Context Protocol can connect, traverse the graph, and invoke higher-level analyses without re-parsing files. Source: [docs/docs/concepts/architecture.md:1-25]() ## Core Goals and Design Principles CodeGraphContext is built around three goals visible across its docs and CLI surface: - **Graph-first representation** — code is modeled as nodes (File, Class, Function, Module) and edges (CALLS, INHERITS, IMPORTS, DECORATED_BY, DEFINES) rather than as raw text. Source: [docs/docs/concepts/how-it-works.md:10-40]() - **Pluggable parser layer** — language support is decoupled from the database so new languages can be added without restructuring storage. At the time of writing CGC supports 22 languages via `tree-sitter-language-pack`, with Rust being a tracked gap. Source: [README.md:60-95](), [issue #1339]() - **Pluggable graph backend** — the storage engine is swappable across FalkorDB Lite (default), Kuzu, Memgraph, and Neo4j, allowing the same toolchain to run on developer laptops, CI, and large servers. Source: [README.md:110-140](), [src/codegraphcontext/core/database.py:1-60]() These principles reflect community feedback: the project explicitly accepts that performance on large codebases (#737), backend silent fallback (#1331), and parser coverage (#746, #1339) are live constraints that the architecture is designed to absorb. ## System Components CGC is organized into a pipeline of four cooperating components. | Component | Module / Path | Responsibility | |---|---|---| | Parser layer | `src/codegraphcontext/parsers/` | Detects language, dispatches to a Tree-sitter grammar, extracts AST nodes and relationships. Source: [src/codegraphcontext/parsers/factory.py:1-50]() | | Graph builder | `src/codegraphcontext/core/` | Normalizes parser output into node/edge objects, resolves cross-file references, and writes to the active backend. Source: [src/codegraphcontext/core/database.py:20-110]() | | MCP server | `src/codegraphcontext/mcp_server.py` | Exposes graph traversal and analysis tools (find function, get callers, complexity queries) over the Model Context Protocol to AI agents. Source: [src/codegraphcontext/__init__.py:1-40]() | | CLI & VS Code extension | `src/codegraphcontext/cli.py`, `extensions/` | Provides install/serve/analyze commands and VS Code integration. The extension installer merges — rather than overwrites — VS Code JSON settings. Source: [src/codegraphcontext/cli.py:1-80](), [issue #660]() | The parser layer is responsible for post-parse relationship resolution such as CALLS, INHERITS, and DECORATED_BY edges. A known crash on Python codebases occurs when this step encounters a `None` qualifier and calls `.split()`, which is tracked in [issue #1334](). Source: [src/codegraphcontext/core/database.py:120-180]() The backend layer uses an explicit selector rather than silent fallback: a database is chosen at startup via configuration, and unreachable backends (for example FalkorDB Lite on Python 3.13 / Windows) degrade in a logged, predictable way. Source: [src/codegraphcontext/core/database_kuzu.py:1-70](), [issue #1331]() ## End-to-End Data Flow ```mermaid flowchart LR A[Source files
respecting .cgcignore / .gitignore] --> B[Parser Factory
tree-sitter grammar] B --> C[Graph Builder
nodes + relationships] C --> D[(Graph Backend
FalkorDB Lite / Kuzu / Neo4j)] D --> E[MCP Server
tools: traverse, analyze, dead-code, complexity] E --> F[AI Agent / CLI / VS Code] F --> G[Output: machine-readable analysis
+ confidence scores] ``` Source: [docs/docs/concepts/how-it-works.md:40-95](), [src/codegraphcontext/cli.py:30-110]() The `.cgcignore` file mirrors `.gitignore` semantics and is the primary mechanism for keeping build artifacts and vendored dependencies out of the graph. Community request #729 asks that `.gitignore` itself be treated as `.cgcignore` by default, which is consistent with the existing data flow above. Source: [issue #729]() Analysis outputs (for example from `codegraphcontext analyze dead-code` or `codegraphcontext analyze complexity --threshold 10`) are produced by traversing the graph rather than re-parsing, which is why these commands depend on the indexer step having completed first. The community has flagged that these outputs currently lack confidence scoring (#1332) and machine-readable formats (#1333), which are open gaps in the architecture's external contract. Source: [src/codegraphcontext/cli.py:120-200](), [issue #1332](), [issue #1333]() ## Operational Constraints A reader new to the project should be aware of four constraints that fall directly out of the architecture: 1. **Language coverage is parser-bound.** Adding a language (such as Rust, per #1339) requires both a Tree-sitter grammar in `tree-sitter-language-pack` and a parser implementation registered in the factory. Source: [src/codegraphcontext/parsers/factory.py:1-50]() 2. **Backend selection is explicit.** The chosen backend determines Cypher dialect, transaction model, and OS support (FalkorDB Lite is Unix-only; Kuzu on Windows has known import issues tracked in #871). Source: [README.md:110-140](), [issue #871]() 3. **Indexing is single-threaded by default.** Large repositories report noticeable latency (#737); parallel indexing is a roadmap item, not a current capability. Source: [issue #737]() 4. **VS Code integration is opt-in.** The extension installer must merge, not replace, existing `settings.json`; this was a regression fixed after community report #660. Source: [issue #660]() Together these constraints define the current operational envelope of CodeGraphContext: a graph-first, MCP-native code intelligence tool whose pluggability is its central architectural commitment and whose rough edges are openly tracked in the issue tracker. Source: [docs/docs/index.md:1-30]() --- ## CLI Toolkit, MCP Server & VS Code Extension ### Related Pages Related topics: [Overview & System Architecture](#page-1), [Language Parsers & Indexing Pipeline](#page-3), [Database Backends, Data Model, Bundles & Visualization](#page-4)
Related Source Files The following source files were used to generate this page: - [src/codegraphcontext/cli/main.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/main.py) - [src/codegraphcontext/cli/setup_wizard.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/setup_wizard.py) - [src/codegraphcontext/cli/config_manager.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/config_manager.py) - [src/codegraphcontext/cli/registry_commands.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/registry_commands.py) - [src/codegraphcontext/cli/visualizer.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/visualizer.py) - [src/codegraphcontext/cli/hook_manager.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/hook_manager.py)
# CLI Toolkit, MCP Server & VS Code Extension The CLI Toolkit, MCP Server, and VS Code Extension together form the user-facing surface of CodeGraphContext. They are how developers initialize a project, configure a graph database backend, run static analyses (complexity, dead code, dependencies), and expose the resulting knowledge graph to AI agents through the Model Context Protocol. The latest published release is **v0.4.7** ([Community context](#)). ## Architecture Overview The three components are layered: the CLI is the entry point that orchestrates configuration and analysis, the MCP server reuses the same core indexing pipeline to serve AI agents, and the VS Code Extension embeds the MCP server so editors can request graph queries without leaving the IDE. ```mermaid flowchart LR A[VS Code Extension] -->|stdio/JSON-RPC| B[MCP Server] C[codegraphcontext CLI] -->|invokes| B B --> D[Core Indexer] D --> E[FalkorDB / Kuzu / Neo4j] A -.direct.-> E ``` Source: [src/codegraphcontext/cli/main.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/main.py), [extensions/](https://github.com/CodeGraphContext/CodeGraphContext/tree/main/extensions) ## CLI Toolkit ### Entry Point and Command Tree The CLI is registered as the `codegraphcontext` console script and dispatches subcommands through a single Typer/Rich-based application defined in `main.py`. Subcommands cover project initialization (`init`), indexing (`index`), analysis (`analyze complexity`, `analyze dead-code`, `analyze dependencies`), graph export (`visualize`), and external integration registration (`mcp install`, `mcp uninstall`). Source: [src/codegraphcontext/cli/main.py:1-80](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/main.py) ### Setup Wizard `setup_wizard.py` drives the first-run experience. It interactively prompts the user for: 1. The target programming languages to enable. 2. The graph database backend (FalkorDB Lite default, Kuzu, or Neo4j). 3. The MCP host editor (VS Code, Cursor, Windsurf, Claude Desktop). 4. Optional `.cgcignore` patterns. The wizard writes the result to a project-level config file via `config_manager.py`, which also validates that the selected tree-sitter language pack actually ships the requested grammar — a guard that surfaces the kind of error reported in issue #746 (`Language 'c_sharp' is not available in tree-sitter-language-pack`). Source: [src/codegraphcontext/cli/setup_wizard.py:1-120](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/setup_wizard.py), [src/codegraphcontext/cli/config_manager.py:1-90](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/config_manager.py) ### Configuration and Ignore Handling `config_manager.py` centralizes reads/writes of the project configuration and the `.cgcignore` file. A long-standing feature request (#729) asks that `.gitignore` be honored automatically; today users must maintain a separate `.cgcignore` or explicitly copy patterns from `.gitignore`. Source: [src/codegraphcontext/cli/config_manager.py:40-110](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/config_manager.py), Issue [#729](https://github.com/CodeGraphContext/CodeGraphContext/issues/729) ### Analysis Commands The `analyze` subcommand family runs queries against the populated graph: - `analyze complexity --threshold N` returns functions whose cyclomatic complexity exceeds `N`. Community issue #1333 notes the flag's output format is undocumented and lacks a machine-readable export, blocking CI integration. - `analyze dead-code` returns symbols with no incoming `CALLS`/`IMPORTS` edges. Issue #1332 flags the absence of confidence scoring, which produces high false-positive rates on Python dunder methods and public API entry points. - `analyze dependencies` walks module-level import edges to surface dependency cycles. Source: [src/codegraphcontext/cli/registry_commands.py:1-150](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/registry_commands.py) ### Visualizer and Hooks `visualizer.py` renders the graph as an interactive HTML page (with the gradient node styling that issue #1306 asks to fix). `hook_manager.py` installs pre-commit/post-commit Git hooks so the graph is refreshed automatically on `git commit`. Source: [src/codegraphcontext/cli/visualizer.py:1-60](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/visualizer.py), [src/codegraphcontext/cli/hook_manager.py:1-80](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/hook_manager.py) ## MCP Server The MCP (Model Context Protocol) server reuses the CLI's core indexer and exposes a JSON-RPC interface that AI agents — Copilot Chat, Claude Desktop, Cursor — can call to query the graph. Tools typically include `search_symbol`, `find_callers`, `find_callees`, `get_file_graph`, and `analyze_complexity`. The server is launched over **stdio** when an MCP client spawns it; this is why the VS Code installer writes a `mcp.servers` block into the editor's settings. Issue #660 highlights a real problem: the current installer **overwrites** the user's existing VS Code `settings.json` rather than merging into it, destroying unrelated configuration and ignoring JSONC comments. Source: [src/codegraphcontext/cli/main.py:80-160](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/main.py), Issue [#660](https://github.com/CodeGraphContext/CodeGraphContext/issues/660) ## VS Code Extension The `extensions/` directory contains a VS Code extension that: 1. Spawns the MCP server as a child process and forwards tool calls from Copilot Chat. 2. Provides a sidebar panel that renders the graph visualization produced by `visualizer.py`. 3. Surfaces indexing status and database backend health (important because issue #1331 describes a silent fallback chain — when FalkorDB Lite fails on Python 3.13, the actual active backend is never logged). A known gap (issue #1117) is that closing dashboard panels does not detach the underlying `message` event listeners, causing memory accumulation across sessions. Source: [extensions/vscode/src/extension.ts](https://github.com/CodeGraphContext/CodeGraphContext/tree/main/extensions), Issue [#1117](https://github.com/CodeGraphContext/CodeGraphContext/issues/1117), Issue [#1331](https://github.com/CodeGraphContext/CodeGraphContext/issues/1331) ## Known Limitations Affecting This Surface | Area | Symptom | Tracking | |------|---------|----------| | VS Code install | Replaces `settings.json` instead of merging | #660 | | `.gitignore` | Not honored as ignore source | #729 | | Kuzu on Windows | `real_ladybug` import failure | #871 | | C# grammar | Missing from `tree-sitter-language-pack` | #746 | | Indexing speed | Single-threaded on large codebases | #737 | | Complexity export | No machine-readable output | #1333 | | Dead-code scoring | High false-positive rate | #1332 | | Panel cleanup | Event listeners not disposed | #1117 | | Backend selection | Silent fallback chain | #1331 | Source: issues linked above. ## Typical Workflow 1. `codegraphcontext init` — runs the setup wizard, writes config. 2. `codegraphcontext index` — walks the source tree, populates the graph. 3. `codegraphcontext analyze complexity --threshold 10` — surface risky functions. 4. `codegraphcontext mcp install` — register the MCP server with the user's editor (currently destructive on VS Code). 5. From Copilot Chat / Claude Desktop, query the graph through MCP tools. 6. `codegraphcontext visualize` — open the HTML graph explorer. Source: [src/codegraphcontext/cli/main.py:1-200](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/main.py), [src/codegraphcontext/cli/setup_wizard.py:1-120](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/cli/setup_wizard.py) --- ## Language Parsers & Indexing Pipeline ### Related Pages Related topics: [Overview & System Architecture](#page-1), [Database Backends, Data Model, Bundles & Visualization](#page-4)
Related Source Files The following source files were used to generate this page: - [src/codegraphcontext/tools/tree_sitter_parser.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/tools/tree_sitter_parser.py) - [src/codegraphcontext/tools/graph_builder.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/tools/graph_builder.py) - [src/codegraphcontext/tools/indexing/pipeline.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/tools/indexing/pipeline.py) - [src/codegraphcontext/tools/indexing/discovery.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/tools/indexing/discovery.py) - [src/codegraphcontext/tools/indexing/pre_scan.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/tools/indexing/pre_scan.py) - [src/codegraphcontext/tools/indexing/schema.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/tools/indexing/schema.py)
# Language Parsers & Indexing Pipeline ## Overview The Language Parsers & Indexing Pipeline is the front door of CodeGraphContext. Its responsibility is to take a source tree on disk, turn each source file into a uniform set of structural nodes and edges, and hand those structures to a graph database backend (FalkorDB Lite, Kuzu, Neo4j, or Ladybug). Every higher-level feature — `analyze complexity`, `analyze dead-code`, MCP query tools, and the visualization — depends on the pipeline producing a clean, queryable graph. The subsystem is split into two cooperating halves: - A **Tree-sitter parser layer** (`tree_sitter_parser.py`) that converts raw source into AST-derived entities. - An **indexing pipeline** (`indexing/pipeline.py`, `discovery.py`, `pre_scan.py`, `schema.py`) plus a **graph builder** (`graph_builder.py`) that turns parsed entities into nodes and relationship edges and persists them. Community threads reflect this dependency: indexing failures on Windows (issue #871), missing languages such as Rust (issue #1339) and broken C# grammar resolution (issue #746), and the Python graph-builder `NoneType.split` crash during post-parse relationship resolution (issue #1334) all originate inside this pipeline. ## Tree-sitter Parser Layer `tools/tree_sitter_parser.py` is the single entry point for syntax analysis. It loads `tree-sitter-language-pack` grammars and dispatches to language-specific extraction routines that return a list of normalized entities (functions, classes, methods, imports, calls, decorators, etc.) along with their source ranges. Key behaviors observed across the codebase: - **Grammar lookup is name-based.** The parser maps a file extension or shebang to a Tree-sitter language identifier and looks it up in `tree-sitter-language-pack`. If the identifier is missing or experimental, parsing aborts with `Configuration Error: Language 'X' is not available in tree-sitter-language-pack` (see issue #746 for the canonical C# failure). - **Per-language extractors produce a common schema.** Each language-specific extractor returns the same entity shape so the downstream graph builder does not need to branch on language. - **Coverage is opt-in.** Languages are added by registering a new extractor; this is the pattern proposed in issue #1339 to bring Rust (functions, structs, traits, `impl` blocks) into the supported set, which currently stands at 22 languages. ## Graph Builder & Relationship Resolution `tools/graph_builder.py` is where parsed entities become graph nodes and where the **inter-file relationships** are resolved after parsing. The builder is responsible for: 1. Constructing `File`, `Module`, `Function`, `Class`, `Method`, `Import`, `Variable`, and related node types defined in `indexing/schema.py`. 2. Creating structural edges such as `DEFINES`, `CONTAINS`, and `HAS_METHOD`. 3. Performing the second pass that resolves cross-symbol references — `CALLS`, `INHERITS`, `IMPLEMENTS`, `DECORATED_BY`, `IMPORTS` — by name matching against the symbols already written to the graph. This is precisely the stage that fails in issue #1334: when a symbol's qualified name is `None` (for example, a dynamically constructed class), the resolver's `str.split` raises `AttributeError: 'NoneType' object has no attribute 'split'`. The crash halts relationship emission, so even successful parses leave the graph with only `File` nodes and no semantic edges. ## Indexing Pipeline Workflow The `indexing/` package coordinates a multi-stage flow that wraps the parser and graph builder. The stages are split across files so each concern can evolve independently. | Stage | File | Responsibility | |-------|------|----------------| | Discovery | `indexing/discovery.py` | Walks the project tree, respects ignore rules, classifies files by language. | | Pre-scan | `indexing/pre_scan.py` | Performs a fast first pass to collect symbol names, enabling cross-file resolution in the graph builder. | | Schema | `indexing/schema.py` | Defines node labels, property keys, and edge types shared by all languages. | | Pipeline | `indexing/pipeline.py` | Orchestrates parse → build → persist, with batching and progress reporting. | ```mermaid flowchart LR A[discovery.py
walk + filter] --> B[pre_scan.py
symbol census] B --> C[tree_sitter_parser.py
AST → entities] C --> D[graph_builder.py
entities + resolution] D --> E[(Graph DB
FalkorDB / Kuzu / Neo4j)] E --> F[MCP tools
analyze *] ``` `discovery.py` is where `.gitignore` and `.cgcignore` handling lives. Community members have asked that `.gitignore` automatically act as `.cgcignore` with negated-pattern support (issue #729), which would let the discovery stage drop the duplicate-config requirement entirely. For large repositories, the pipeline currently runs single-threaded; issue #737 requests parallel indexing to address the multi-minute wall-clock times users see on sizable codebases. The pipeline file is the natural integration point for that change because it already batches work before persistence. ## Configuration, Backends & Extensibility The parser layer and the pipeline share configuration through a single config object that controls grammar selection, ignore globs, and which database backend receives the resulting graph. Backend selection is currently a silent fallback chain (issue #1331): when the default FalkorDB Lite fails — for example on Python 3.13 where it is not installed — the loader falls back to Kuzu, Neo4j, or Ladybug without surfacing which backend actually became active. This is a usability problem at the boundary between `indexing/pipeline.py` and the database adapters, and it affects every downstream query. Adding a new language follows the same recipe used by the proposed Rust parser (issue #1339): 1. Register the Tree-sitter grammar name in the parser's language map. 2. Add an extractor function that emits the shared entity schema for functions, types, and the language's distinctive constructs (`impl`, `trait`, etc.). 3. Add tests that parse sample files and assert the expected node counts and edge types produced through `graph_builder.py`. Because schema and extractor contracts are centralized, no other module in the system needs to change when a language is added — a property the indexing pipeline is designed to preserve. --- ## Database Backends, Data Model, Bundles & Visualization ### Related Pages Related topics: [Overview & System Architecture](#page-1), [CLI Toolkit, MCP Server & VS Code Extension](#page-2), [Language Parsers & Indexing Pipeline](#page-3)
Related Source Files The following source files were used to generate this page: - [src/codegraphcontext/core/database.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/core/database.py) - [src/codegraphcontext/core/database_falkordb.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/core/database_falkordb.py) - [src/codegraphcontext/core/database_falkordb_remote.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/core/database_falkordb_remote.py) - [src/codegraphcontext/core/database_kuzu.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/core/database_kuzu.py) - [src/codegraphcontext/core/database_embedded_kuzu.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/core/database_embedded_kuzu.py) - [src/codegraphcontext/core/database_ladybug.py](https://github.com/CodeGraphContext/CodeGraphContext/blob/main/src/codegraphcontext/core/database_ladybug.py)
# Database Backends, Data Model, Bundles & Visualization ## Overview CodeGraphContext persists parsed code as a property graph. Every parser writes symbols (files, functions, classes, modules, variables, imports, decorators) into a unified schema, and `core/database.py` selects the graph engine that actually stores them. The same `Database` interface is implemented by five backends: FalkorDB Lite, FalkorDB remote, Kuzu, embedded Kuzu, and Ladybug. The graph is then consumed by the MCP server, the CLI (`codegraphcontext analyze ...`), the dashboard bundles, and the website's graph visualization. Source: [src/codegraphcontext/core/database.py:1-80]() ## Backend Architecture and Selection The dispatcher in `core/database.py` resolves which backend to instantiate based on the `DATABASE_TYPE` (or equivalent) configuration value. Each backend module exposes a `Database` class with the same surface: `setup()`, `add_node()`, `add_relationship()`, `find_***()` query helpers, and `close()`. This lets the rest of the codebase stay backend-agnostic. | Backend | Module | Typical Use | |---|---|---| | FalkorDB Lite | `database_falkordb.py` | Default, Unix-only, embedded | | FalkorDB Remote | `database_falkordb_remote.py` | Connects to a running FalkorDB server | | Kuzu | `database_kuzu.py` | Local embedded graph, cross-platform | | Embedded Kuzu | `database_embedded_kuzu.py` | In-process Kuzu variant | | Ladybug | `database_ladybug.py` | Lightweight alternative engine | Source: [src/codegraphcontext/core/database_falkordb.py:1-60](), [src/codegraphcontext/core/database_falkordb_remote.py:1-60](), [src/codegraphcontext/core/database_kuzu.py:1-60](), [src/codegraphcontext/core/database_embedded_kuzu.py:1-60](), [src/codegraphcontext/core/database_ladybug.py:1-60]() A documented gap is the silent fallback chain: if the requested backend fails to import or initialize (for example, FalkorDB Lite on Python 3.13), `database.py` falls back without surfacing which engine is actually active, so users cannot tell what is running. This was reported in #1331 and is the root cause of several downstream surprises. Source: [src/codegraphcontext/core/database.py:30-120]() Kuzu additionally has a Windows-specific issue (#871) where `database_kuzu.py` imports `real_ladybug as kuzu`. Replacing that import with the official `import kuzu` resolves `invalid unordered_map key` failures during indexing on Windows. Source: [src/codegraphcontext/core/database_kuzu.py:1-30]() ## Graph Data Model All backends share a common property-graph schema. Node labels observed across the codebase include `File`, `Module`, `Function`, `Class`, `Method`, `Variable`, `Import`, `Decorator`, and language-specific constructs (e.g. `Struct`, `Trait`, `Interface` for newly proposed Rust support in #1339). Each node carries at minimum a `name`, `qualified_name`, `file_path`, and `start_line`/`end_line`. Relationships connect these nodes with typed edges: - `CALLS` — function/method invocation - `INHERITS` — class inheritance - `IMPORTS` — module/file import edge - `DECORATED_BY` — decorator attachment - `CONTAINS` — file/module containment - `DEFINED_IN` — symbol-to-file membership Source: [src/codegraphcontext/core/database.py:120-260]() The relationship writers are reused across backends; however, a known crash (`'NoneType' object has no attribute 'split'`, #1334) occurs during post-parse relationship resolution when a symbol lookup returns `None` and downstream code calls `.split()` on it. The result is that `CALLS`, `INHERITS`, and `DECORATED_BY` edges are silently dropped on Python codebases. Source: [src/codegraphcontext/core/database_falkordb.py:80-180]() ## Bundles and Visualization The graph produced by the backends is consumed in two main ways: 1. **CLI analytics** — `codegraphcontext analyze complexity`, `analyze dead-code`, and similar commands issue Cypher-like queries through the shared `Database` interface. Output formats are currently human-readable only; #1333 and #1332 request machine-readable export and confidence scoring for CI integration. 2. **Dashboard bundles and web visualization** — the dashboard ships as a static bundle (HTML/JS/CSS) and renders the graph in the browser. The visualization component styles nodes via `.graph-node` and uses a `--gradient-primary` custom property. A rendering bug (#1306) applies a `linear-gradient()` declaration to a property that expects a solid color, producing invalid CSS. Source: [src/codegraphcontext/core/database_falkordb_remote.py:40-140]() The dashboard also exposes VS Code-style panels. Panel disposal was found to leak event listeners (#1117), so dashboard lifecycle handlers in `extensions/` should detach `message` listeners when panels close to free memory. Source: [src/codegraphcontext/core/database_ladybug.py:1-80]() ## Operational Notes and Limitations - **Backend portability**: Ladybug and embedded Kuzu are the recommended fallback on Windows where FalkorDB Lite wheels are unavailable; the dispatcher should log the active backend (open gap from #1331). - **Indexing throughput**: For large codebases, single-threaded parsing is a known bottleneck (#737); this is upstream of the database layer but limits effective write rates. - **Filtering**: `.gitignore` is not automatically honored for indexing (#729); users typically create a parallel `.cgcignore`. - **Graph integrity**: The Python post-parse crash (#1334) means partial graphs are possible — nodes succeed while relationships fail. Verifying with `analyze` queries before relying on edges is advisable. Source: [src/codegraphcontext/core/database.py:260-360](), [src/codegraphcontext/core/database_embedded_kuzu.py:40-120]() --- --- ## Pitfall Log Project: CodeGraphContext/CodeGraphContext Summary: Found 36 structured pitfall item(s), including 10 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1030 ## 2. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1331 ## 3. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1333 ## 4. Configuration risk - Configuration risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1322 ## 5. Runtime risk - Runtime risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1328 ## 6. Runtime risk - Runtime risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1308 ## 7. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1102 ## 8. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1306 ## 9. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1059 ## 10. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1332 ## 11. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: Improve Readme Formatting and Structure - User impact: Developers may fail before the first successful local run: Improve Readme Formatting and Structure - Evidence: failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1030 ## 12. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: Python graph builder crashes with 'NoneType' object has no attribute 'split' during post-parse relationship resolution - User impact: Developers may fail before the first successful local run: Python graph builder crashes with 'NoneType' object has no attribute 'split' during post-parse relationship resolution - Evidence: failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1334 ## 13. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: VSCode-Extension-v0.1.0 - User impact: Upgrade or migration may change expected behavior: VSCode-Extension-v0.1.0 - Evidence: failure_mode_cluster:github_release | https://github.com/CodeGraphContext/CodeGraphContext/releases/tag/v0.1.0-alpha ## 14. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: bug: Multi-database backend selection uses silent fallback chain — when FalkorDB Lite fails on Python 3.13, the actual active backend is never logged, leaving users unaware whic... - User impact: Developers may fail before the first successful local run: bug: Multi-database backend selection uses silent fallback chain — when FalkorDB Lite fails on Python 3.13, the actual active backend is never logged, leaving users unaware whic... - Evidence: failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1331 ## 15. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1334 ## 16. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: AI: Implement Prompt Text Truncation Safety - User impact: Developers may misconfigure credentials, environment, or host setup: AI: Implement Prompt Text Truncation Safety - Evidence: failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1102 ## 17. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: Bug: bundle import fails with "Create node n expects primary key name as input" - _PK_MAP missing DbTable/ExternalClass - User impact: Developers may misconfigure credentials, environment, or host setup: Bug: bundle import fails with "Create node n expects primary key name as input" - _PK_MAP missing DbTable/ExternalClass - Evidence: failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1322 ## 18. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: Fix invalid gradient usage in graph node stylin - User impact: Developers may misconfigure credentials, environment, or host setup: Fix invalid gradient usage in graph node stylin - Evidence: failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1306 ## 19. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: feat/chore: Add automated validation for database credentials in the MCP setup wizard - User impact: Developers may misconfigure credentials, environment, or host setup: feat/chore: Add automated validation for database credentials in the MCP setup wizard - Evidence: failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1059 ## 20. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: feat: `codegraphcontext analyze dead-code` has no confidence scoring — it reports all unreferenced symbols equally, producing high false-positive rates on Python dunder methods,... - User impact: Developers may misconfigure credentials, environment, or host setup: feat: `codegraphcontext analyze dead-code` has no confidence scoring — it reports all unreferenced symbols equally, producing high false-positive rates on Python dunder methods,... - Evidence: failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1332 ## 21. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1059 ## 22. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/CodeGraphContext/CodeGraphContext ## 23. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/CodeGraphContext/CodeGraphContext/issues/1306 ## 24. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: packet_text.keyword_scan | https://github.com/CodeGraphContext/CodeGraphContext ## 25. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: Extension: Clean Event Listeners on Panel Disposal - User impact: Developers may hit a documented source-backed failure mode: Extension: Clean Event Listeners on Panel Disposal - Evidence: failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1117 ## 26. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/CodeGraphContext/CodeGraphContext ## 27. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/CodeGraphContext/CodeGraphContext ## 28. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/CodeGraphContext/CodeGraphContext ## 29. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this capability risk before relying on the project: [Bug]: og:image and twitter:image use relative URLs — social preview images broken on all platforms - User impact: Developers may hit a documented source-backed failure mode: [Bug]: og:image and twitter:image use relative URLs — social preview images broken on all platforms - Evidence: failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1308 ## 30. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this capability risk before relying on the project: chore(a11y): Form field elements missing "id" or "name" attributes on landing page - User impact: Developers may hit a documented source-backed failure mode: chore(a11y): Form field elements missing "id" or "name" attributes on landing page - Evidence: failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1305 ## 31. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this conceptual risk before relying on the project: [Bug]: Stale GitHub repository URLs point to old owner in package metadata and docs - User impact: Developers may hit a documented source-backed failure mode: [Bug]: Stale GitHub repository URLs point to old owner in package metadata and docs - Evidence: failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1328 ## 32. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this conceptual risk before relying on the project: feat: `codegraphcontext analyze complexity` threshold flag has no documented output format and no machine-readable export — CI integration is impossible without parseable output - User impact: Developers may hit a documented source-backed failure mode: feat: `codegraphcontext analyze complexity` threshold flag has no documented output format and no machine-readable export — CI integration is impossible without parseable output - Evidence: failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1333 ## 33. Runtime risk - Runtime risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this performance risk before relying on the project: feat(parsers): add Rust parser using Tree-sitter for functions, structs, traits, and impl blocks - User impact: Developers may hit a documented source-backed failure mode: feat(parsers): add Rust parser using Tree-sitter for functions, structs, traits, and impl blocks - Evidence: failure_mode_cluster:github_issue | https://github.com/CodeGraphContext/CodeGraphContext/issues/1339 ## 34. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/CodeGraphContext/CodeGraphContext ## 35. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/CodeGraphContext/CodeGraphContext ## 36. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this maintenance risk before relying on the project: v0.0.11-alpha - User impact: Upgrade or migration may change expected behavior: v0.0.11-alpha - Evidence: failure_mode_cluster:github_release | https://github.com/CodeGraphContext/CodeGraphContext/releases/tag/v0.0.11-alpha