Cosmic Vault Graph

What happens when you treat knowledge management as a design problem? Cosmic Vault Graph is the answer I built — an open-source Obsidian plugin that renders your entire knowledge vault as an interactive 3D cosmic map, powered by Three.js force-directed simulation.

The Problem

Obsidian's built-in graph view is two-dimensional and structurally blind. It renders every note as an identical node, which works fine for small vaults but falls apart at scale. In a real knowledge base, some notes are gravitational centers — hubs that connect dozens of topics and serve as wayfinding landmarks. Others are leaf fragments, referenced once and rarely revisited. The default graph flattens that hierarchy into visual noise.

Navigating a large vault through the built-in view means squinting at an undifferentiated cloud of dots. There's no immediate sense of what matters, what clusters with what, or where you are relative to the structure of your own thinking.

How It Works

Cosmic Hierarchy

The core idea is that connectivity is meaning. Cosmic Vault Graph classifies every note by its structural role in the vault and assigns it a corresponding cosmic type: supernovas are highly connected hub notes, stars are well-connected topic notes, planets are standard notes with moderate links, moons attach to a single parent, comets are orphaned notes with no connections, and asteroids are small fragments.

This isn't decoration. The metaphor maps directly to structural reality — a supernova in the graph is genuinely a hub in your thinking, a comet genuinely isolated. The visual language makes vault topology immediately readable in a way abstract nodes and edges never achieve. You can orient yourself at a glance.

Force Simulation

The layout uses spring physics with orbital mechanics. Notes that link to each other attract; unrelated notes repel. The result is that related content clusters naturally without manual arrangement. Topic neighborhoods emerge from the link structure itself.

The simulation runs in three modes: settling (initial layout, actively finding equilibrium), settled (stable, low-energy state), and focus-lock (a selected note centered with its neighborhood pulled close). Switching modes is instant — focus-lock in particular makes the graph feel less like a visualization and more like a navigation tool.

Rendering Pipeline

Rendering hundreds of 3D nodes at 60fps required some care. The key unlock was Three.js InstancedMesh — rather than creating a separate draw call per node, all nodes of a given type share a single instanced mesh with per-instance transforms. This collapses what would be hundreds of draw calls into a handful, which is what makes the plugin viable on mid-range hardware.

On top of that: bloom glow for the brighter node types, depth-sorted transparency for the layered cosmic feel, particle trails on active nodes, and LOD management to reduce geometry complexity for distant nodes. The bloom in particular is what makes supernovas feel significant — the visual weight matches the structural weight.

Working Within Obsidian

Building for an existing platform's extension model means accepting constraints that feel arbitrary until you understand the security model behind them. Obsidian's plugin API forbids innerHTML — all DOM construction must go through createEl(). No network requests. No dynamic code execution. The API surface is deliberately narrow.

These restrictions exist because Obsidian vaults often contain sensitive personal knowledge, and a plugin ecosystem without strict sandboxing would be a liability. Once that framing clicked, working within the constraints felt less like fighting the platform and more like collaborating with it. The codebase is cleaner for it — no innerHTML means no accidental XSS surface, no dynamic execution means the plugin's behavior is fully auditable at read time.

What I Learned

The central tension in this project was visual richness versus performance. Bloom and trails look genuinely stunning. They also cost frames. Finding the budget — how much visual effect the rendering pipeline could carry before frame time started climbing — required profiling individual passes and making deliberate tradeoffs rather than just adding features until something broke.

The cosmic metaphor wasn't just an aesthetic choice. It was a design decision that made the graph immediately usable. Abstract graphs require you to learn a mapping between visual properties and structural meaning. The cosmic hierarchy skips that step — people already have intuitions about stars versus moons versus asteroids. The metaphor did interpretive work that I would otherwise have had to build into a legend or tutorial.

Building for a platform extension model also taught me something about shipping into ecosystems. You inherit the platform's constraints, its security assumptions, its API idioms. The question isn't whether to work within them — it's how to build something genuinely useful given what the platform allows.

Outcome

v1.0.0, open source under MIT. The project demonstrates creative frontend engineering within real platform constraints, 3D performance optimization at meaningful scale, and the kind of design thinking that makes a technically competent tool actually pleasant to use.