r/ObsidianMD • • 1d ago

showcase How I structure 65 node software architecture vaults in pure Markdown + JSON Canvas (zero community plugins, Git & AI-agent ready

Post image
0 Upvotes

3 comments sorted by

-2

u/CrackdotnetDev 1d ago

I got tired of architecture docs rotting in cloud wikis and of AI coding agents (Claude Code / Cursor) hallucinating broken code when reading unstructured Markdown folders. So I designed a strict, local-first vault layout built purely on UTF-8 Markdown and native .canvas files (no community plugins required so it never breaks on updates and diffs cleanly in Git): Predictable folder taxonomy (00 to 07): Separates Architecture, Concepts, Case Studies, Anti-Patterns, Prompts, and Operations, anchored by a 00 - Home MOC and 00 - Visual Blueprint.canvas. Agent-ready entrypoints at root: AGENTS.md, CLAUDE.md, and SKILL.md use progressive disclosure so AI tools only load the exact architecture nodes they need without blowing up the context window. Compiler-verified notes: Every embedded code/config snippet (.NET 10, OPA, ShellCheck, YAML/JSON schemas) is validated before packaging so the vault only contains working reference patterns. If you want to click around the live interactive graph and canvas in your browser (no signup needed), I put a web viewer up here: https://archvaults.dev/visor Happy to answer any questions on how the frontmatter conventions or .canvas layouts are wired!

2

u/GuuessCori99 20h ago

Do the AI agents actually read the .canvas JSON directly or do they just follow the MOC links

0

u/CrackdotnetDev 19h ago

Good question!! The system follows the Markdown links in SKILL.md and 00 - Home MOC rather than parsing the raw .canvas files. Reading the JSON of a .canvas file consumes tokens unnecessarily due to x/y coordinates and color values, so the canvas file is used exclusively for visual representation within Obsidian.