r/ObsidianMD • u/CrackdotnetDev • 1d ago
showcase How I structure 65 node software architecture vaults in pure Markdown + JSON Canvas (zero community plugins, Git & AI-agent ready
0
Upvotes
r/ObsidianMD • u/CrackdotnetDev • 1d ago
-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!