NxtSoftLabs
CGRAPH DOCS — CONTENTS
CGRAPH

Graph Model

CGraph represents a codebase as a directed graph of nodes and links, serialized as node-link JSON (graph.json). This page describes what those nodes and links mean.

Nodes

Nodes are the entities extracted from the source tree — the files, symbols, and declarations that make up a codebase (files, symbols, functions, classes, and the references between them). Semantic enrichment can add further nodes, such as documents that describe parts of the code.

Note

The canonical set of node kinds is defined by the extractor in the CGraph src/engine code rather than enumerated in the public README. Treat the list above as the categories of things captured, not a closed enum — this page will be pinned to the exact kinds once they are confirmed against the source.

Links

Links are directed edges between nodes. They come from the resolution stage:

  • Imports — from import resolution, connecting a file or module to what it pulls in.
  • Calls — from raw call resolution, connecting a caller to a callee (the basis of the call-flow export).
  • Relations — from relation resolution, plus semantic relations added during enrichment (for example, a describes relation from a document to code).
file  --imports-->  file
fn    --calls----->  fn
doc   --describes->  symbol
A directed graph of code entities and their relationships

Why a graph

Two questions drive the model: what calls this? and what breaks if I change it? Both are graph traversals — the first walks incoming call edges, the second walks the transitive blast radius of a node. Expressing code as a graph makes these first-class queries instead of heuristic text searches.

Tradeoffs

  • Precision vs. recall — a resolved graph gives precise relationships, but resolution is only as good as extraction; dynamic dispatch and reflection are hard to resolve statically, so some call edges are approximate.
  • Structure, not semantics — the base graph captures how code connects, not what it means. Semantic meaning is layered in optionally via enrichment.

Exports

The same graph is written in several shapes: graph.json (the canonical node-link form), graph.html and graph.svg (visual), obsidian.md (a vault), cypher.txt (for graph databases), and call-flow.html (the call graph).

Where to go next

  • Memory — how the graph is stored and kept warm.
  • Architecture — the extraction and resolution pipeline in depth.
← PREVIOUS
Core Concepts
NEXT →
Memory