Build Your First Graph

Fresh

Overview

This SOP walks you through building your first Graphify knowledge graph from scratch — from pointing Graphify at a directory to interpreting the output.

What You'll Build

flowchart TD
    A[Your Codebase] --> B{/graphify .}
    B --> C[Tree-sitter AST\nfor code files]
    B --> D[LLM extraction\nfor docs/prose]
    B --> E[Vision model\nfor images/diagrams]
    C --> F[NetworkX Graph]
    D --> F
    E --> F
    F --> G[Leiden Clustering]
    G --> H[graph.html]
    G --> I[graph.json]
    G --> J[GRAPH_REPORT.md]

Step 1: Navigate to Your Project

cd /path/to/your/project

Step 2: Run Graphify

/graphify .

This processes the current directory recursively, excluding common noise directories (node_modules, .git, dist, etc.).

Process by Specific Subfolder

/graphify ./src
/graphify ./docs

Run in Deep Mode (More Inferred Edges)

/graphify . --mode deep

Deep mode uses more aggressive inference extraction to find relationships that aren't explicitly stated in the code.

Step 3: Review the Output

After the run completes, you'll have:

graphify-out/
├── graph.html           ← Open this in your browser
├── GRAPH_REPORT.md      ← Read this first
├── graph.json           ← Used for queries and updates
└── cache/               ← Do not delete — enables incremental rebuilds

Reading GRAPH_REPORT.md

The report tells you:

Section	What It Means
God Nodes	Highest-degree concepts — the core of your system
Community Clusters	Semantic groupings Leiden found
Surprising Connections	Cross-file or cross-domain edges worth investigating
Suggested Questions	Queries that will give rich graph traversal results

Edge Types

Every relationship in the graph is tagged with one of three types:

Type	Meaning
EXTRACTED	Found directly in source (function calls, imports, explicit references)
INFERRED	Reasonable guess based on context (same namespace, similar naming)
AMBIGUOUS	Found but confidence is low — review before acting

Step 4: Query the Graph

/graphify query "what handles authentication"
/graphify path "UserController" "Database"
/graphify explain "AuthMiddleware"

Step 5: Update the Graph Incrementally

After making code changes:

/graphify . --update

Only changed files are re-extracted. The graph merges new nodes and edges into the existing graph.json.

Step 6: Explore the Visualization

Open graphify-out/graph.html in your browser. You can:

• Click nodes to see their relationships
• Filter by community cluster
• Search for specific nodes
• Zoom and pan the graph

Verification Checklist

• [ ] graphify-out/graph.html opens in browser without error
• [ ] GRAPH_REPORT.md shows at least one God Node
• [ ] /graphify query "..." returns relevant results
• [ ] Community clusters reflect the logical structure of your codebase

First-Run Performance

The first run on a large codebase may take several minutes — LLM extraction for prose/docs is the slow step. Subsequent runs with --update are fast because only changed files are reprocessed.