Graphify Overview

Graphify Overview

What Graphify is, how it works, and why it’s useful for understanding codebases.

🎯 What is Graphify?

Graphify is a local knowledge graph builder for codebases. It analyzes your project (code, docs, markdown, configs) and builds a queryable graph of files, symbols, and relationships. You ask natural language questions and get architectural answers with file references.

┌─────────────────────────────────────────────────────────────┐
│                     YOUR CODEBASE                             │
│  Python, JS/TS, Go, Rust, Java, Markdown, YAML, PDF, ...   │
└─────────────────────┬───────────────────────────────────────┘
                      │ AST + Semantic Extraction
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                    KNOWLEDGE GRAPH                            │
│  Nodes: files, functions, classes, variables, docs          │
│  Edges: imports, calls, contains, references, reads, writes │
│  Communities: auto-detected logical groups                   │
└─────────────────────┬───────────────────────────────────────┘
                      │ Natural Language Queries
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                        ANSWERS                                │
│  "How does X work?" → Architectural explanation + files     │
│  "What depends on Y?" → Dependency list + paths             │
│  "Trace A to B" → Call/import chain with line numbers       │
└─────────────────────────────────────────────────────────────┘

🔑 Key Concepts

Knowledge Graph

A network of nodes (files, functions, classes, variables, docs) connected by edges (relationships like imports, calls, contains, reads, writes).

Natural Language Queries

Ask questions in plain English: “How does the YouTube pipeline work?” — Graphify traverses the graph and synthesizes an answer citing specific files and lines.

Two Modes

🎯 Why Use Graphify?

For Developers

• Onboard faster — “Project overview” in seconds, not hours
• Debug smarter — Trace bugs through call chains, not grep
• Refactor safely — “What depends on this?” before changing
• Understand legacy — Navigate unfamiliar codebases confidently

For Architects

• System overview — See module boundaries, coupling, data flows
• Impact analysis — “If I change X, what breaks?”
• Documentation sync — Verify docs match implementation
• Decision support — Data-driven architecture decisions

For Teams

• Shared knowledge — Graph persists, doesn’t leave with people
• CI/CD integration — Auto-rebuild on merge, detect drift
• Cost control — Local-first, free code-only mode; API only for docs

🔄 How It Works

1. Extraction

Code files     → tree-sitter AST → functions, classes, imports, calls
Markdown/docs  → LLM semantic → headings, prose, code blocks, refs
YAML/JSON      → Parser → structure, keys, cross-refs
PDFs           → OCR + LLM → text, sections
Images         → Vision LLM → descriptions

2. Graph Construction

• Nodes = Files, symbols (functions, classes, vars), doc sections
• Edges = imports_from, calls, contains, references, reads, writes
• Communities = Louvain clustering → named groups (e.g., “YouTube Pipeline”)

3. Query Processing

User Question → LLM → Graph Traversal → Subgraph → LLM Synthesis → Answer + Citations

💰 Cost Model

Free tier (Gemini): ~1M tokens/day → ~3-10 full builds/day free

🏗️ This Project’s Graph

Built with graphify . --code-only:

Communities detected: YouTube Pipeline, Dictionary System, Anki Generation, Hugo Build, CBT Lexicon, JupyterLite, Skills, Config, Tests, …

🚀 Quick Start

 1# 1. Install (one-time)
 2uv tool install graphifyy && graphify install
 3
 4# 2. Build code-only graph (free, fast)
 5cd your-project
 6mkdir -p graphify-out && touch graphify-out/.graphify-activity
 7graphify . --code-only
 8
 9# 3. Ask your first question
10mkdir -p graphify-out && touch graphify-out/.graphify-activity
11graphify query "project overview"

📚 Documentation Structure

• Getting Started — Installation, setup, first query
• Workflows — Daily usage, architecture queries, dependency tracing, impact analysis
• Guides — Code-only vs full, API keys, rebuilding, VS Code, ignoring files
• Reference — Commands, node IDs, edge types, troubleshooting, config

🎯 Next Steps

1. New to Graphify? → Getting Started
2. Want to query now? → Daily Usage
3. Need full graph? → Adding API Keys
4. VS Code user? → VS Code Integration