Graphify: One-Click Code Architecture Graphs for Legacy Java & Microservices

How It Generates Graphs

Traditional code RAG chunks files, computes embeddings, stores in vector databases, and retrieves by similarity. This approach has three unavoidable pitfalls: retrieval is fuzzy — asking "which tables does the auth flow touch" may return a file merely named auth, but vectors cannot reveal actual imports or calls; reindexing costs money on every code change; and vector databases are black boxes with no auditability.

Graphify takes a direct approach: code is structured data with AST syntax trees providing nodes and edges, no need for vector detours. It uses tree-sitter for deterministic parsing, supporting ~40 languages including .java, .kt, .scala. An import becomes an imports edge, a function call becomes a calls edge, class B extends A becomes an inherits edge. All runs locally, no LLM calls, zero token cost.

What the Generated Graph Looks Like

Every edge carries a confidence label, which is the most valuable design. EXTRACTED edges are explicitly in source code and can be used as facts. INFERRED edges come from second-pass call graph analysis (e.g., cross-file indirect calls) and should be weighed before use. AMBIGUOUS edges are uncertain and flagged for manual review. This transparency distinguishes extracted from inferred — something vector retrieval cannot provide.

A detail in the source code maintains language-family boundaries, discarding cross-language inference edges because of a real incident where Python's import time accidentally bound to a file named time.ts (issue #1749). Only genuine cross-language interoperability is retained. Such edge-case handling shows the project has been battle-tested in real use.

After parsing, it runs the Leiden community detection algorithm to split the codebase into subsystems by edge density — no embeddings, no vector database, graph topology alone suffices. The output graph.html opens in a browser; same-color nodes belong to the same subsystem, and clicking any node jumps to the source location.

GRAPH_REPORT.md

includes God nodes — the highest-degree nodes across the project. In Java projects, these are typically the universally imported Utils class or a BaseService coupling the entire system. A newcomer reading the report immediately sees the project's critical coupling points.

Query Methods

Once the graph is built, you query instead of browsing files. Official example output on the FastAPI codebase:

$ graphify explain "APIRouter"
Node: APIRouter
  Source:   routing.py L2210
  Community: 2
  Degree:   47

$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField

query

answers natural language questions, path traces call paths between two classes, explain clarifies a concept's origins. All queries run against the persisted graph.json without re-reading source files.

Installation

Two commands to install:

uv tool install graphifyy
graphify install

The PyPI package is temporarily named graphifyy (the graphify name is being reclaimed). After installation, run /graphify . in your AI assistant to start.

Large projects take minutes for the initial graph build; thereafter it's incremental. SHA256 caching remembers each file's parse result, --update processes only changed files. For more automation, graphify hook install adds a git post-commit hook to rebuild on every commit. --watch mode updates the graph instantly on file save — pure AST, no LLM — keeping the graph current even with multiple AI agents writing code in parallel.

CI environments can run headless: graphify extract ./src --code-only performs pure code indexing fully offline, zero API keys. Document, PDF, and image semantic extraction requires a model, but the backend can be swapped to a self-hosted Ollama instance, keeping data inside the network.

Microservice Architecture Governance

The official recommendation is to commit graphify-out/ to git so every team member clones the repository with the map built-in. This recommendation embodies the governance philosophy: the graph versions with code, eliminating "documentation stuck three years ago."

In microservice scenarios, generate a graph per repository. New hires generate graph.html for their service, exploring subsystem divisions by clicking nodes — an order of magnitude faster than reading docs. During architecture reviews, track God node trend changes; a class's steadily growing degree signals architectural decay. For reporting and archiving, --neo4j emits Cypher scripts for Neo4j import, --graphml exports to Gephi or yEd for visualization. Database introspection is also supported: graphify extract --postgres introspects a live PostgreSQL schema into the graph.

When It's Suitable

Suitable for: Java teams burdened with legacy systems, experiencing team turnover, wanting architecture governance without budget for commercial tools. Not suitable for: those needing runtime full-chain tracing — that's APM territory; graphs cover static structure only.

Limitations

Graph processing uses NetworkX, a pure Python implementation, so performance caps out on graphs with hundreds of thousands of nodes. Document and image semantic extraction quality depends on the configured model — a weak model yields a rough graph. One critical limitation for Java projects: Spring's dependency injection, reflection, AOP, and other runtime-determined relationships are inherently invisible to static AST analysis; this portion of the graph can only serve as reference, not ground truth.

Author's Perspective

Documentation always lags — not an attitude problem but a mechanism problem: documentation and code are two manually maintained artifacts that inevitably diverge. Graphify's solution turns "documentation" into a code derivative, auto-regenerated on every commit, eliminating lag at the mechanism level.