# How to Explain a Node in the Graphify Graph: A Complete Guide

> Learn how to explain a node in the Graphify graph with `graphify explain`. Get human-readable descriptions, relationships, and lessons for any code concept. Explore the Graphify knowledge graph today.

- Repository: [Graphify Labs/graphify](https://github.com/Graphify-Labs/graphify)
- Tags: how-to-guide
- Published: 2026-07-16

---

**Run `graphify explain "<node-name>"` to generate a human-readable description of any code concept stored in the Graphify knowledge graph, including its relationships and annotated lessons.**

Graphify, developed by Graphify-Labs, converts your codebase into a persistent knowledge graph stored in the `graphify-out/` directory. When you need to understand what a specific class, function, or module represents without reading raw source files, you can explain a node in the Graphify graph to receive a contextual summary. This command leverages the aggregated graph structure to deliver fast, stable descriptions that include hand-written lessons and relationship mappings.

## The `graphify explain` Command Syntax

The `explain` sub-command is the primary interface for retrieving node descriptions from the Graphify knowledge graph.

### Basic Usage

To explain a node, pass the concept name as a quoted argument:

```bash
graphify explain "RateLimiter"

```

This queries the default graph at [`graphify-out/graph.json`](https://github.com/Graphify-Labs/graphify/blob/main/graphify-out/graph.json) and returns a plain-language summary describing the node's type, purpose, and key relationships.

### Advanced Options

For custom graph locations or specific output requirements, use the `--graph` flag:

```bash
graphify explain "SwinTransformer" --graph /tmp/custom-graph.json

```

You can also redirect the output to generate documentation files:

```bash
graphify explain "SwinTransformer" > docs/knowledge/SwinTransformer.md

```

## How Node Explanation Works Under the Hood

According to the Graphify-Labs/graphify source code, the explanation process follows a four-stage pipeline that transforms graph data into readable text.

### Node Lookup and Resolution

In [`graphify/cli.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/cli.py), the `explain` sub-command first searches the aggregated graph ([`graphify-out/graph.json`](https://github.com/Graphify-Labs/graphify/blob/main/graphify-out/graph.json)) for a node whose label matches the supplied name. When multiple matches exist, the system selects the most specific node, typically prioritizing file-level nodes over broader matches. This resolution ensures you receive the most relevant context for the requested concept.

### Neighbour Extraction

Once the target node is identified, Graphify gathers its immediate neighbours by traversing both incoming and outgoing edges. This extraction captures how the node is used, defined, or referenced throughout the codebase, including relationships like `calls`, `imports`, `defines`, and `explains`.

### Reasoning and Summarisation

The [`graphify/extract.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/extract.py) module plays a critical role in this stage. For each neighbouring node, Graphify retrieves:

- **Source location**: The specific file and line number where the relationship occurs
- **Lesson annotations**: Concise, hand-written explanations embedded in source files as comments

If a lesson annotation exists for a neighbour, the system displays it directly. Otherwise, [`graphify/extract.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/extract.py) falls back to generic descriptions derived from the edge type (e.g., "calls", "imports", "explains"). This hybrid approach combines human-authored context with automated relationship mapping.

### Plain-Language Output Generation

The final stage formats the collected data into a structured paragraph that includes:

- The node's type (class, function, file, or module)
- A brief summary or lesson if available
- A list of relevant neighbours with one-sentence rationales for each edge

Because this process operates on the pre-built graph rather than grepping raw source files, results are **fast**, **deterministic**, and **free of duplicate noise**.

## Practical Code Examples

### Explain a Class and Its Consumers

```bash
$ graphify explain "RateLimiter"

# → "RateLimiter is a class that throttles API calls. It is instantiated

#    in `src/utils/api.ts` and referenced by the `AuthService` to ensure

#    we never exceed the provider's request quota."

```

### Explain a Function's Import Chain

```bash
$ graphify explain "fetchData"

# → "`fetchData` is an async helper that retrieves JSON from the backend.

#    It is defined in `src/lib/network.ts` and is imported by

#    `src/components/dashboard.tsx` and `src/services/report.ts`."

```

### Generate Documentation from Specific Graph Files

```bash
graphify explain "AuthService" --graph ./alternate-graph.json > ./docs/auth-service.md

```

## Key Implementation Files

Understanding the following files helps you customize or debug the explanation process:

- **[`graphify/cli.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/cli.py)**: Implements the `explain` argument parser, node lookup logic, and formatted output printing.
- **[`graphify/serve.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/serve.py)**: Provides the HTTP API endpoint `/explain` that mirrors CLI behavior for web-based integrations.
- **[`graphify/extract.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/extract.py)**: Extracts lesson annotations from source files and attaches them to graph nodes during the reasoning phase.
- **[`graphify/querylog.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/querylog.py)**: Optional logging module that records each `explain` request for auditing or debugging purposes.
- **[`docs/how-it-works.md`](https://github.com/Graphify-Labs/graphify/blob/main/docs/how-it-works.md)**: High-level documentation describing the Graphify pipeline and the purpose of node explanations.
- **[`docs/node-summaries-rfc.md`](https://github.com/Graphify-Labs/graphify/blob/main/docs/node-summaries-rfc.md)**: Specification document defining the node-level summary format that `explain` surfaces.

## Summary

- **Use `graphify explain "<node>"`** to retrieve human-readable descriptions of any code concept in your knowledge graph.
- The command queries [`graphify-out/graph.json`](https://github.com/Graphify-Labs/graphify/blob/main/graphify-out/graph.json) and resolves the most specific node match when multiple candidates exist.
- Explanations combine **lesson annotations** (hand-written comments) with **edge-derived relationships** to provide context.
- The process operates on the aggregated graph, making it faster and more stable than text-based source searching.
- Implementation spans [`graphify/cli.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/cli.py) for CLI logic, [`graphify/extract.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/extract.py) for annotation processing, and [`graphify/serve.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/serve.py) for HTTP API access.

## Frequently Asked Questions

### How does Graphify choose which node to explain when multiple nodes share the same name?

When multiple nodes match the supplied name, Graphify selects the most specific node, typically prioritizing file-level nodes over broader or more generic matches. This resolution logic in [`graphify/cli.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/cli.py) ensures you receive the most contextually relevant explanation for the requested concept.

### Can I explain a node using a custom graph file instead of the default?

Yes. Use the `--graph` flag to specify an alternative path: `graphify explain "NodeName" --graph /path/to/custom-graph.json`. This allows you to generate explanations from historical graph snapshots or independently generated knowledge graphs.

### What are "lesson" annotations and how do they appear in explanations?

Lessons are concise, hand-written explanations embedded as comments in your source code and extracted by [`graphify/extract.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/extract.py). When present, they appear directly in the explanation output as the primary description of a node or relationship. If no lesson exists, Graphify falls back to generic descriptions based on edge types like `calls` or `imports`.

### Is there an HTTP API equivalent to the `graphify explain` command?

Yes. The [`graphify/serve.py`](https://github.com/Graphify-Labs/graphify/blob/main/graphify/serve.py) module exposes an `/explain` endpoint that mirrors the CLI behavior. This allows web-based tools and integrations to request node explanations programmatically without invoking the command line interface.