{"slug": "we-invented-a-layered-wiki-pattern-on-top-of-graphify-here-s-the-concept-and-how", "title": "We Invented a Layered Wiki Pattern on Top of Graphify — Here's the Concept and How to Approximate It Today", "summary": "A developer proposed a layered wiki pattern on top of the open-source tool graphify, which turns codebases into queryable knowledge graphs. The design suggests colocating scoped graphs and wikis within each layer of a monorepo, using a `.graphify/` directory convention instead of the default `graphify-out/`, to reduce noise and improve context for AI assistants. The proposal includes a `needs_update` staleness marker and a global cross-layer graph, though these features are not yet part of the official tool.", "body_md": "Transparency note:This post describes adesign patternwe invented on top of[graphify], an existing open-source tool. The core tool is real. The layered wiki structure and`.graphify/`\n\nfolder convention described here arenotofficial 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.\n\nIf you haven't used graphify yet, the short version: you run `/graphify .`\n\ninside Claude Code (or `graphify . --wiki`\n\nfrom 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.\n\nIt works brilliantly for single-service repos. But for a monorepo that looks like this:\n\n```\nmy-repo/\n├── frontend/       ← TypeScript / React\n├── api/            ← Java / Spring Boot\n├── services/\n│   ├── order-service/    ← .NET / C#\n│   └── notification-worker/  ← Python\n└── database/       ← SQL stored procedures\n```\n\n…you hit a wall. Run `graphify .`\n\nat the root and everything lands in a single flat `graphify-out/`\n\nfolder. The community articles generated by the `--wiki`\n\nflag 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.\n\nThe real question: **what if each layer had its own scoped graph and wiki, colocated with the source it describes?**\n\n⚠️\n\nEverything 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.\n\nInstead of one `graphify-out/`\n\nat the root, we imagined a two-level structure:\n\n```\nmy-repo/\n│\n├── .graphify/                    ← 🌐 global cross-layer graph\n│   ├── graph.json                   commit this ✓\n│   ├── GRAPH_REPORT.md              commit this ✓\n│   ├── graph.html                   commit this ✓\n│   ├── needs_update                 staleness marker (gitignored)\n│   ├── .gitignore                   auto-generated exclude list\n│   └── wiki/\n│       ├── index.md                 commit this ✓\n│       └── Community_0.md           commit this ✓\n│\n├── frontend/\n│   └── .graphify/                ← 🎨 frontend-only graph\n│       ├── graph.json\n│       ├── GRAPH_REPORT.md\n│       └── wiki/\n│           └── index.md\n│\n├── api/\n│   └── .graphify/                ← ☕ Java API graph\n│       └── wiki/\n│\n├── services/order-service/\n│   └── .graphify/                ← 🔷 .NET service graph\n│       └── wiki/\n│\n└── database/\n    └── .graphify/                ← 🗄️ SQL graph\n        └── wiki/\n```\n\nTwo levels of granularity, both queryable:\n\n`.graphify/`\n\nInstead of `graphify-out/`\n\nThe real tool writes to `graphify-out/`\n\n. We proposed renaming this to `.graphify/`\n\n— a small but deliberate signal.\n\n`graphify-out/`\n\nreads like a build artefact — something to gitignore, like `dist/`\n\nor `build/`\n\n. Developers instinctively expect build artefacts to be throwaway, regenerated on demand, never committed.\n\n`.graphify/`\n\nreads like a tool-config directory — something to commit and version, like `.github/`\n\n, `.husky/`\n\n, or `.vscode/`\n\n. 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.\n\n`needs_update`\n\nStaleness Marker\nThe second invented piece was a `needs_update`\n\nfile inside each `.graphify/`\n\ndirectory, 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.\"*\n\nThe proposed hooks:\n\n```\n# Proposed commands (not real)\ngraphify hook install        # registers post-commit, post-checkout, post-merge hooks\ngraphify check-update api/  # reads needs_update and reports staleness\n```\n\nThe designed workflow:\n\n```\ngit commit  →  hook writes .graphify/needs_update\n              ↓\nClaude Code reads next query  →  detects needs_update  →  prompts rebuild\n              ↓\ngraphify update api/  →  deletes needs_update, rebuilds graph\n```\n\nWith each layer having its own wiki, the proposed `CLAUDE.md`\n\nentry gave Claude a lookup table of which wiki to open based on the layer being worked in:\n\n```\n## Graphify Knowledge Graph\n\n| Layer | Language | Wiki |\n|---|---|---|\n| Global | all layers | `.graphify/wiki/index.md` |\n| Frontend | TypeScript | `frontend/.graphify/wiki/index.md` |\n| API | Java | `api/.graphify/wiki/index.md` |\n| Order Service | .NET / C# | `services/order-service/.graphify/wiki/index.md` |\n| Database | SQL | `database/.graphify/wiki/index.md` |\n```\n\nClaude would pick the narrowest applicable wiki for each question, then widen to the global graph for cross-layer questions.\n\nThese felt natural to design, but none of them exist in the real tool today:\n\n| Invented command | What we wanted it to do |\n|---|---|\n`graphify update api/` |\nBuild/refresh a specific layer's graph |\n`graphify export wiki --graph api/.graphify/graph.json --dir api/.graphify/wiki` |\nRegenerate wiki without rebuilding the full graph |\n`graphify merge-graphs frontend/.graphify/graph.json api/.graphify/graph.json --out .graphify/graph.json` |\nCompose the global graph from layer graphs |\n`graphify hook install` |\nRegister git hooks that stamp `needs_update`\n|\n`graphify check-update api/` |\nRead `needs_update` and report staleness |\n`graphify install claude --project` |\nProject-local skill install |\n`graphify migrate-state --root api/` |\nMigrate a layer from `graphify-out/` to `.graphify/`\n|\n`graphify summary` |\nPrint a compact graph summary for AI context |\n\nThe real tool (installed as `pip install graphifyy`\n\n, used as `graphify`\n\n) 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.\n\n```\npip install graphifyy       # PyPI package is graphifyy (double-y)\ngraphify --version          # should print 0.9.41\ngraphify install            # registers the /graphify skill in Claude Code\n```\n\nRun `graphify`\n\nseparately from each layer. Each invocation produces its own `graphify-out/`\n\ninside that directory:\n\n```\n# Global — from repo root\ngraphify . --wiki\n\n# Per layer\ncd frontend && graphify . --wiki && cd ..\ncd api && graphify . --wiki && cd ..\ncd services/order-service && graphify . --wiki && cd ../..\ncd database && graphify . --wiki && cd ..\n```\n\nRun layers in parallel (separate terminals) to save time on large repos.\n\n`.graphify/`\n\nconvention (optional)\nThe real tool doesn't care what the output folder is named once it's written. Rename freely:\n\n```\nmv frontend/graphify-out frontend/.graphify\nmv api/graphify-out api/.graphify\nmv services/order-service/graphify-out services/order-service/.graphify\nmv database/graphify-out database/.graphify\nmv graphify-out .graphify\n```\n\nQuery against the renamed folder using `--graph`\n\n:\n\n```\ngraphify query \"auth flow\" --graph frontend/.graphify/graph.json\ngraphify explain \"OrderController\" --graph api/.graphify/graph.json\ngraphify path \"CheckoutForm\" \"PaymentService\" --graph .graphify/graph.json\n# Exclude only the incremental cache\necho \"cache/\" >> .graphify/.gitignore\necho \"cache/\" >> frontend/.graphify/.gitignore\necho \"cache/\" >> api/.graphify/.gitignore\n\ngit add .graphify/ frontend/.graphify/ api/.graphify/ database/.graphify/\ngit commit -m \"chore: add graphify knowledge graphs and layer wikis\"\n```\n\nAdd this to your project's `CLAUDE.md`\n\nso Claude knows where each wiki lives:\n\n```\n## Graphify Knowledge Graph\n\n| Layer | Language | Wiki |\n|---|---|---|\n| Global | all layers | `.graphify/wiki/index.md` |\n| Frontend | TypeScript | `frontend/.graphify/wiki/index.md` |\n| API | Java | `api/.graphify/wiki/index.md` |\n| Database | SQL | `database/.graphify/wiki/index.md` |\n\nQuery commands:\ngraphify query \"<question>\" --graph <layer>/.graphify/graph.json\ngraphify explain \"<class or function>\" --graph <layer>/.graphify/graph.json\ngraphify path \"<source>\" \"<target>\" --graph <layer>/.graphify/graph.json\n\nRefresh a layer:\ncd <layer> && graphify . --update --wiki\nmv <layer>/graphify-out <layer>/.graphify\n```\n\nSince `graphify hook install`\n\ndoesn't exist, use a simple git alias as a substitute:\n\n``` bash\n# Add to .git/hooks/post-commit (make it executable)\n#!/bin/sh\ntouch .graphify/needs_update\nfor dir in frontend api services/order-service database; do\n  [ -d \"$dir/.graphify\" ] && touch \"$dir/.graphify/needs_update\"\ndone\necho \"graphify: graphs marked stale — run 'cd <layer> && graphify . --update --wiki' to refresh\"\nchmod +x .git/hooks/post-commit\n```\n\nThis is a manual implementation of what we designed as `graphify hook install`\n\n. It's eight lines of shell instead of one command, but it works.\n\nIf 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:\n\n`graphify update <path>`\n\n`cd`\n\n`graphify hook install`\n\n`graphify merge-graphs`\n\n`.graphify/`\n\ncan be the default instead of `graphify-out/`\n\nFeel free to open or upvote issues for these on [github.com/Graphify-Labs/graphify](https://github.com/Graphify-Labs/graphify).\n\n| Official graphify today | Layered wiki pattern (this post) | |\n|---|---|---|\n| Output folder | `graphify-out/` |\n`.graphify/` (renamed) |\n| Granularity | one graph per `graphify .` run |\none graph per layer (manual runs) |\n| Wiki |\n`graphify-out/wiki/` with `--wiki` flag |\nper-layer `.graphify/wiki/`\n|\n| Staleness | none | manual git hook writing `needs_update`\n|\n| CLAUDE.md | your choice | layer lookup table |\n| Cross-layer graph | run at root | run at root + merge (no merge command yet) |\n\nThe 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.\n\n*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.*", "url": "https://wpnews.pro/news/we-invented-a-layered-wiki-pattern-on-top-of-graphify-here-s-the-concept-and-how", "canonical_source": "https://dev.to/arun_bhat/we-invented-a-layered-wiki-pattern-on-top-of-graphify-heres-the-concept-and-how-to-approximate-32d9", "published_at": "2026-08-14 09:15:00+00:00", "updated_at": "2026-08-14 09:35:42.222692+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["graphify", "Claude Code"], "alternates": {"html": "https://wpnews.pro/news/we-invented-a-layered-wiki-pattern-on-top-of-graphify-here-s-the-concept-and-how", "markdown": "https://wpnews.pro/news/we-invented-a-layered-wiki-pattern-on-top-of-graphify-here-s-the-concept-and-how.md", "text": "https://wpnews.pro/news/we-invented-a-layered-wiki-pattern-on-top-of-graphify-here-s-the-concept-and-how.txt", "jsonld": "https://wpnews.pro/news/we-invented-a-layered-wiki-pattern-on-top-of-graphify-here-s-the-concept-and-how.jsonld"}}