How BrainShare Works (Behind the Scenes)

The thing that frustrates me about most "publish your notes" tools is they make you choose between everything and nothing. Either your whole vault goes out into the world, or you paste one note into a Google Doc and lose all the structure that made it useful in the first place.

BrainShare started as a simple question: what if you could hand someone a curated slice of your brain, graph intact, wikilinks navigable, sidebar and all, and take it back whenever you wanted? That's the whole premise. The tech is just in service of that.

Here's what actually happens under the hood.

When you click "Publish"

The Obsidian plugin does two things before it sends anything. First, it checks whether the note already has an id in its frontmatter. If not, it stamps one, a 26-character ULID, time-sortable, globally unique, generated locally. That ID is the note's stable identity. Rename the file or move it to a different folder. The ID doesn't change. Cross-vault links survive because of this.

Then it sends the raw markdown to your Cloudflare Worker via PUT /api/notes/:ulid, with the file path tucked into a request header. That's it. No transformation on the client side. The markdown goes up as-is.

The worker writes three things to Cloudflare KV:

• note:{ulid}: the raw markdown body
• meta:{ulid}: a small JSON blob with the file path, basename, and folder
• wrap:{id}: a descriptor for the slice (set of ULIDs + title + access config), created when you bundle notes into a shareable wrapper

Binary blobs go under asset:{sha256}. Obsidian canvas JSON under canvas:{ulid}. The schema is flat and intentional, no SQL, no relations, no migrations. KV is eventually consistent, which means a note you just published might take a few hundred milliseconds to appear at every Cloudflare edge. In practice you don't notice. And the free tier handles real traffic without breaking a sweat.

How rendering works

Every page served at /share/{wrapId}/{ulid} is one HTTP response. No client-side framework, no hydration, no JavaScript bundle that needs to boot before you can read. The worker renders the full HTML on the server and sends it down.

The renderer reconstructs the Obsidian experience server-side: it parses wikilinks from the markdown, checks each link target against the wrapper's share-set (the list of ULIDs that belong to this slice), and decides whether to render it as a live navigable link or a "private" pill. If the target note is in the share-set, you get a real link. If it's not (maybe it's a note you chose not to share), the link renders as a grayed-out pill that says "private." The recipient never sees raw markdown; they never see your unshared notes. They see exactly what you chose to surface.

Backlinks, folder tree, properties panel, callout blocks, all of it is reconstructed at render time. No Obsidian running on the server. Just string parsing and some careful HTML templating.

The design philosophy

I kept the primitives small on purpose. KV is a dumb key-value store. The worker is a single TypeScript file that handles routing, auth, and rendering. The Obsidian plugin is a thin HTTP client with a ULID stamper. Each piece is replaceable.

Your data is yours in a literal sense: the worker exports everything as NDJSON on demand (GET /api/export). You can take the raw KV dump and reconstruct your notes anywhere. There's no proprietary format, no vendor-specific graph encoding. It's markdown all the way down.

I built this as a beginning. The rendering is plain, no Mermaid, no math blocks yet. The mobile experience needs work. I hope to find a better solution for some of these gaps soon. But the foundation, stable IDs, scoped sharing, self-hosted infra you control, that part I'm confident about.

If any of this resonates, the place to start is Install BrainShare in 60 Seconds. And if you want to understand why I made some of the bigger architectural bets, Many Brains, One Web gets into the federation layer.

This note was published using BrainShare itself. Which felt like the right way to launch it. Start with A letter for my fellow viewers.