We Invented a Layered Wiki Pattern on Top of Graphify — Here's the Concept and How to Approximate It Today

arun bhat — Fri, 14 Aug 2026 09:15:00 +0000

"Graphify turns codebases into queryable knowledge graphs. We designed a layered monorepo wiki extension — per-layer .graphify/ folders with staleness hooks — that doesn't exist yet. Here's the full spec and how to get 90% of it right now."

Transparency note: This post describes a design pattern we invented on top of graphify, an existing open-source tool. The core tool is real. The layered wiki structure and .graphify/ folder convention described here are not official graphify features — they are a proposal. We'll clearly mark every invented part. The "how to approximate it today" sections use only real, working graphify commands.

The Problem: One Graph, Many Layers

If you haven't used graphify yet, the short version: you run /graphify . inside Claude Code (or graphify . --wiki from your terminal), and it turns your entire codebase into a queryable knowledge graph. Claude can then answer questions like "how does the checkout flow work?" or "what calls PaymentService?" with file-and-line citations instead of hallucinated guesses.

It works brilliantly for single-service repos. But for a monorepo that looks like this:

my-repo/
├── frontend/       ← TypeScript / React
├── api/            ← Java / Spring Boot
├── services/
│   ├── order-service/    ← .NET / C#
│   └── notification-worker/  ← Python
└── database/       ← SQL stored procedures

…you hit a wall. Run graphify . at the root and everything lands in a single flat graphify-out/ folder. The community articles generated by the --wiki flag end up mixing TypeScript React components with Java Spring controllers with SQL stored procedures. When you're deep inside the frontend layer fixing a component, Claude is also loading a wiki article about your database trigger — noise you don't need.

The real question: what if each layer had its own scoped graph and wiki, colocated with the source it describes?

The Concept: Layered Graphify Wiki

⚠️ Everything in this section is a design proposal — not official graphify. The folder names, behaviours, and some commands below do not exist in the real tool. Skip to How to Approximate It Today if you only want working commands.

The Proposed Folder Layout

Instead of one graphify-out/ at the root, we imagined a two-level structure:

my-repo/
│
├── .graphify/                    ← 🌐 global cross-layer graph
│   ├── graph.json                   commit this ✓
│   ├── GRAPH_REPORT.md              commit this ✓
│   ├── graph.html                   commit this ✓
│   ├── needs_update                 staleness marker (gitignored)
│   ├── .gitignore                   auto-generated exclude list
│   └── wiki/
│       ├── index.md                 commit this ✓
│       └── Community_0.md           commit this ✓
│
├── frontend/
│   └── .graphify/                ← 🎨 frontend-only graph
│       ├── graph.json
│       ├── GRAPH_REPORT.md
│       └── wiki/
│           └── index.md
│
├── api/
│   └── .graphify/                ← ☕ Java API graph
│       └── wiki/
│
├── services/order-service/
│   └── .graphify/                ← 🔷 .NET service graph
│       └── wiki/
│
└── database/
    └── .graphify/                ← 🗄️ SQL graph
        └── wiki/

Two levels of granularity, both queryable:

Global graph — for cross-layer questions: "how does the UI checkout call the Java payment endpoint?"
Per-layer graph — for day-to-day work: "what React hooks does CheckoutForm use?" with no SQL noise

Why `.graphify/` Instead of `graphify-out/`

The real tool writes to graphify-out/. We proposed renaming this to .graphify/ — a small but deliberate signal.

graphify-out/ reads like a build artefact — something to gitignore, like dist/ or build/. Developers instinctively expect build artefacts to be throwaway, regenerated on demand, never committed.

.graphify/ reads like a tool-config directory — something to commit and version, like .github/, .husky/, or .vscode/. The graph and the wiki are not throwaway; they are knowledge artefacts that accumulate value over time, and they should live in git alongside the code they describe.

The `needs_update` Staleness Marker

The second invented piece was a needs_update file inside each .graphify/ directory, written by a git hook after every commit, checkout, or merge. Claude Code would read this marker before answering a query and prompt: "The graph for this layer is stale — run graphify update api/ to rebuild."

The proposed hooks:

# Proposed commands (not real)
graphify hook install        # registers post-commit, post-checkout, post-merge hooks
graphify check-update api/  # reads needs_update and reports staleness

The designed workflow:

git commit  →  hook writes .graphify/needs_update
              ↓
Claude Code reads next query  →  detects needs_update  →  prompts rebuild
              ↓
graphify update api/  →  deletes needs_update, rebuilds graph

The Invented CLAUDE.md Block

With each layer having its own wiki, the proposed CLAUDE.md entry gave Claude a lookup table of which wiki to open based on the layer being worked in:

## Graphify Knowledge Graph

| Layer | Language | Wiki |
|---|---|---|
| Global | all layers | `.graphify/wiki/index.md` |
| Frontend | TypeScript | `frontend/.graphify/wiki/index.md` |
| API | Java | `api/.graphify/wiki/index.md` |
| Order Service | .NET / C# | `services/order-service/.graphify/wiki/index.md` |
| Database | SQL | `database/.graphify/wiki/index.md` |

Claude would pick the narrowest applicable wiki for each question, then widen to the global graph for cross-layer questions.

Full List of Invented Commands

These felt natural to design, but none of them exist in the real tool today:

Invented command	What we wanted it to do
`graphify update api/`	Build/refresh a specific layer's graph
`graphify export wiki --graph api/.graphify/graph.json --dir api/.graphify/wiki`	Regenerate wiki without rebuilding the full graph
`graphify merge-graphs frontend/.graphify/graph.json api/.graphify/graph.json --out .graphify/graph.json`	Compose the global graph from layer graphs
`graphify hook install`	Register git hooks that stamp `needs_update`
`graphify check-update api/`	Read `needs_update` and report staleness
`graphify install claude --project`	Project-local skill install
`graphify migrate-state --root api/`	Migrate a layer from `graphify-out/` to `.graphify/`
`graphify summary`	Print a compact graph summary for AI context

How to Approximate It Today

The real tool (installed as pip install graphifyy, used as graphify) supports none of the invented commands above. But you can get to about 90% of the layered wiki pattern right now using only real commands.

Step 1 — Install graphify

pip install graphifyy       # PyPI package is graphifyy (double-y)
graphify --version          # should print 0.9.41
graphify install            # registers the /graphify skill in Claude Code

Step 2 — Build per-layer graphs

Run graphify separately from each layer. Each invocation produces its own graphify-out/ inside that directory:

# Global — from repo root
graphify . --wiki

# Per layer
cd frontend && graphify . --wiki && cd ..
cd api && graphify . --wiki && cd ..
cd services/order-service && graphify . --wiki && cd ../..
cd database && graphify . --wiki && cd ..

Run layers in parallel (separate terminals) to save time on large repos.

Step 3 — Rename to the `.graphify/` convention (optional)

The real tool doesn't care what the output folder is named once it's written. Rename freely:

mv frontend/graphify-out frontend/.graphify
mv api/graphify-out api/.graphify
mv services/order-service/graphify-out services/order-service/.graphify
mv database/graphify-out database/.graphify
mv graphify-out .graphify

Query against the renamed folder using --graph:

graphify query "auth flow" --graph frontend/.graphify/graph.json
graphify explain "OrderController" --graph api/.graphify/graph.json
graphify path "CheckoutForm" "PaymentService" --graph .graphify/graph.json

Step 4 — Commit the artefacts

# Exclude only the incremental cache
echo "cache/" >> .graphify/.gitignore
echo "cache/" >> frontend/.graphify/.gitignore
echo "cache/" >> api/.graphify/.gitignore

git add .graphify/ frontend/.graphify/ api/.graphify/ database/.graphify/
git commit -m "chore: add graphify knowledge graphs and layer wikis"

Step 5 — Wire up CLAUDE.md

Add this to your project's CLAUDE.md so Claude knows where each wiki lives:

## Graphify Knowledge Graph

| Layer | Language | Wiki |
|---|---|---|
| Global | all layers | `.graphify/wiki/index.md` |
| Frontend | TypeScript | `frontend/.graphify/wiki/index.md` |
| API | Java | `api/.graphify/wiki/index.md` |
| Database | SQL | `database/.graphify/wiki/index.md` |

Query commands:
graphify query "<question>" --graph <layer>/.graphify/graph.json
graphify explain "<class or function>" --graph <layer>/.graphify/graph.json
graphify path "<source>" "<target>" --graph <layer>/.graphify/graph.json

Refresh a layer:
cd <layer> && graphify . --update --wiki
mv <layer>/graphify-out <layer>/.graphify

Step 6 — Manual staleness check (in place of the invented hook)

Since graphify hook install doesn't exist, use a simple git alias as a substitute:

# Add to .git/hooks/post-commit (make it executable)
#!/bin/sh
touch .graphify/needs_update
for dir in frontend api services/order-service database; do
  [ -d "$dir/.graphify" ] && touch "$dir/.graphify/needs_update"
done
echo "graphify: graphs marked stale — run 'cd <layer> && graphify . --update --wiki' to refresh"

chmod +x .git/hooks/post-commit

This is a manual implementation of what we designed as graphify hook install. It's eight lines of shell instead of one command, but it works.

What We'd Love to See in Official Graphify

If you've made it this far and agree this pattern is worth having, the graphify team is active on GitHub. The features we'd most want upstreamed:

graphify update <path> — build/refresh a specific subdirectory without cd
graphify hook install — register git hooks that stamp a staleness marker
graphify merge-graphs — compose a global graph from per-layer graphs
Official support for a configurable output directory — so .graphify/ can be the default instead of graphify-out/

Feel free to open or upvote issues for these on github.com/Graphify-Labs/graphify.

Summary

	Official graphify today	Layered wiki pattern (this post)
Output folder	`graphify-out/`	`.graphify/` (renamed)
Granularity	one graph per `graphify .` run	one graph per layer (manual runs)
Wiki	`graphify-out/wiki/` with `--wiki` flag	per-layer `.graphify/wiki/`
Staleness	none	manual git hook writing `needs_update`
CLAUDE.md	your choice	layer lookup table
Cross-layer graph	run at root	run at root + merge (no merge command yet)

The real tool is excellent as-is. This pattern is about taking it one step further for teams running large polyglot monorepos with Claude Code as their primary AI assistant.

If you try this pattern and improve on it, please share — especially if you find a cleaner way to handle staleness detection or the CLAUDE.md layer routing.

DEV Community: arun bhat