Your First Knowledge Graph

By the end of this lesson, you'll have a working knowledge graph of your DocumentDB Performance Test infrastructure and understand what the three output files are for.

What Graphify Does

When you point an AI assistant at a large codebase, it has two bad options: read every file (blowing the context window) or guess which files matter (missing connections). Graphify gives it a third option: read a structured map of your code's relationships — classes, functions, imports, call chains — then only read the actual files it needs.

The mechanism is tree-sitter AST parsing. It pulls structure from your code locally (nothing leaves your machine) and writes three files:

• graph.json — the full graph: nodes (entities) and edges (relationships). This is what the AI queries.
• GRAPH_REPORT.md — a human-readable summary: key concepts, surprising connections, suggested questions to ask.
• graph.html — interactive visualization: click nodes, filter by type, search.

Step 1: Install the Kiro Skill

Navigate to your DocumentDB project root and run:

cd ~/path/to/documentdb-perf-tests
graphify kiro install

This writes a .kiro/skills/graphify/ directory and a steering file into the project so Kiro CLI knows about the /graphify command.

Step 2: Build the Graph

From the project root:

graphify .

Or, if you want to run it from elsewhere:

graphify /absolute/path/to/project

This takes 10–60 seconds depending on codebase size. Tree-sitter parses every Python file and extracts:

• Classes, functions, methods
• Import relationships
• Call graphs (who calls whom)
• Inline rationale comments (# WHY: and # HACK: prefixes)

After extraction, Graphify clusters related nodes into communities (groups of tightly-connected code). This is what makes the report useful — it names the clusters so you can navigate by concept, not by file.

Step 3: Inspect the Output

Open the visualization:

open graphify-out/graph.html

And read the report:

cat graphify-out/GRAPH_REPORT.md

The report will show you:

• Communities — named clusters of related code (e.g., "Test Framework Assertions", "MongoDB Connection Management")
• Key nodes — the most-connected entities (often the core abstractions)
• Suggested questions — things you can ask the AI that the graph can answer efficiently

Step 4: Use It in a Session

Start a new Kiro CLI session in the project and type:

/graphify

The AI assistant will load graph.json as context instead of reading your entire codebase. It can then answer structural questions like:

• "What calls execute_command()?"
• "Show me all test files that use the assertResult helper"
• "What's the dependency chain from BaseTestCase to the actual test runner?"

Key Concepts

• Node — an entity in your code: a class, function, module, or file.
• Edge — a relationship: "imports", "calls", "inherits from", "defined in".
• Community — a cluster of nodes that are more connected to each other than to the rest of the graph. Named by the LLM during clustering.
• graph.json — the machine-readable graph. This is what costs tokens — but far fewer than reading all files.

Verify Your Understanding

Do This Now

1. Navigate to your DocumentDB Performance Test infrastructure project
2. Run graphify kiro install
3. Run graphify .
4. Open graphify-out/graph.html in your browser and explore the communities
5. Read graphify-out/GRAPH_REPORT.md — note which clusters it found