# Graph Model
> What CGraph's nodes and links represent, and how the graph is shaped.
[Source](https://open.nxtsoft.io/docs/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.

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).

_A directed graph of code entities and their relationships_

```text
file  --imports-->  file
fn    --calls----->  fn
doc   --describes->  symbol
```

## 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](/docs/cgraph/memory) — how the graph is stored and kept warm.
- [Architecture](/docs/cgraph/architecture) — the extraction and resolution pipeline in depth.