silverbulletmd/silverbullet

1. Overall shape

SilverBullet is a two-part system: a browser client written in TypeScript and a Rust backend that serves the client, stores/serves the space, and runs server-side services. The product is a local-first notes/database app centered on Markdown pages, but the architecture is closer to a programmable runtime than a conventional web app.

2. Client runtime in the browser

The client/ tree contains the main application logic: editor, navigation, page picker, command palette, datastore abstractions, sync engine, service worker, and the Space Lua runtime. The frontend is built on CodeMirror 6 for editing, Preact for UI, and ESBuild for bundling. In practice, much of the app behavior lives in the client rather than the server.

3. Editor and content pipeline

The editor pipeline spans Markdown parsing/rendering, live preview, code widgets, wiki links, tables, tasks, and custom syntax. The client transforms raw page text into structured views and editor decorations, then back into document edits. This is the core interactive loop for page editing.

4. Local-first data model

The client/data/ and client/spaces/ modules show that the app has a layered local storage model: in-memory, IndexedDB, encrypted variants, and sync-aware datastore primitives. A service worker and sync engine coordinate offline operation and eventual synchronization with the server. This makes local browser state a first-class boundary, not just a cache.

5. Space abstraction and synchronization

The repository models a “Space” as the unit of content and synchronization. client/spaces/ implements checked, filtered, HTTP-backed, evented, and datastore-backed space primitives, while server-common/src/space/ provides the corresponding Rust-side implementations for disk, memory, HTTP, readonly, and embedded spaces. This is the main persistence boundary in the system.

6. Server responsibilities

The Rust server/ crate is the HTTP/control plane. It provides routing, authentication, filesystem access, runtime endpoints, shell access, SSR, metrics, and bundle serving. The server is not the primary application engine; it is the host for static assets, authenticated access, and server-side capabilities.

7. Authentication and access control

server/src/auth/ contains login, cookies, JWT authorization, headless tokens, lockout, and authorizer/authenticator logic. This indicates a security boundary around space access and administrative control, with the server enforcing identity before exposing file and runtime APIs.

8. Server-side runtime and Lua execution

SilverBullet includes a server runtime for executing Space Lua outside the browser. server-runtime-chrome/ manages a headless Chrome-based runtime backend, supervised and transported from Rust. This is important because many programmable features depend on executing Lua with DOM/runtime-like capabilities in a controlled environment.

9. Plugin system as the extension boundary

The plugs/ directory contains built-in plugs that implement major product features such as editor enhancements, indexing/querying, configuration management, sync, emoji, image viewing, and object graph visualization. Plugs are compiled and packaged separately, and they extend the app through the PlugOS API rather than by patching the core.

10. PlugOS and syscall boundary

client/plugos/ and plug-api/ define the plugin protocol, syscall interfaces, sandboxing, manifests, and runtime hooks. This is a critical architectural seam: plugs run in isolated sandboxes and interact with the host through typed syscalls for datastore, editor, markdown, shell, config, sync, and related services.

11. Shared Rust foundations

server-common/ is the shared Rust crate for cross-cutting types, crypto, upgrade logic, and space primitives. It keeps the backend binaries aligned and prevents duplication between the server and the standalone runtime-related components. This shared layer is the low-level foundation under the HTTP server and embedded space handling.

12. Build and distribution pipeline

The repo is organized around separate build products: the TypeScript client bundle, built plugs, and Rust binaries. bin/silverbullet is the main self-hosted server binary, bin/sb is the CLI, and the various Dockerfiles/package scripts support release packaging. A release build embeds the client bundle into the Rust binary, while debug development serves the bundle from disk.

13. Documentation and libraries as shipped content

docs/ and libraries/ are not just documentation; they are part of the shipped content model. The libraries provide built-in page templates, slash templates, and Space Lua references that become part of the user space experience. That makes “content” an architectural artifact alongside code.

14. Key runtime flow to diagram

A useful high-level flow is: browser loads the bundled client from the Rust server → client opens a Space via local storage and/or HTTP sync → edits update the local datastore immediately → sync propagates changes to the server space backend → plugs and Space Lua augment behavior through syscalls and runtime services → server optionally executes Lua/headless services and returns results to the client. This captures the main data and control paths without overfocusing on any one subsystem.