SilverBullet

SilverBullet is a local‑first Progressive Web App that turns a collection of Markdown files into a fully‑featured personal knowledge base. From the developer’s standpoint, it exposes its entire content layer as a set of Objects stored on disk and mirrored in the browser’s IndexedDB. The server side is a minimal HTTP API that serves static assets and handles file sync, while the client implements an offline‑first data store, conflict resolution, and a live preview engine. This architecture gives developers tight control over data persistence while still offering the convenience of a web interface.

Technical Stack

• Frontend: Vanilla JavaScript (ES6+), Web Components, and a custom templating engine that interprets ${lua expression} syntax. The UI is built with a lightweight framework (similar to LitElement) and relies on Service Workers for offline caching.
• Scripting: A sandboxed Lua dialect (Space Lua) is embedded via fengari or a native WebAssembly module, allowing users to write inline scripts that manipulate Objects, generate dynamic content, and register custom commands.
• Backend: A Node.js/Express server (or a Go binary) that exposes CRUD endpoints for Markdown files, handles WebSocket or long‑polling sync, and serves the PWA assets. The data layer is simply a file system watch on a designated folder; no external database is required.
• Storage: Markdown files are stored in plain text on the server’s file system. In the browser, a local IndexedDB instance mirrors the file tree, enabling full offline operation and fast lookups.

Core Capabilities

• Bi‑directional Linking: [[page]] syntax is parsed into a link graph; incoming links are surfaced as “Linked Mentions” without any additional configuration.
• Object Querying: Every page, tag, or custom object becomes a searchable record. Developers can write Lua queries like query from index.tag "task" where not _.done and iterate over results with template.each.
• Dynamic Rendering: Templates written in Markdown can embed Lua expressions, enabling runtime content generation (e.g., a task list that auto‑updates).
• Command Palette & Shortcuts: A built‑in command system exposes actions via Cmd-/ or Ctrl-/, and developers can add new commands through Lua plugins.
• Extensibility: The Plugs system allows loading additional JavaScript modules or Lua scripts that augment core features, add new UI components, or expose REST endpoints.

Deployment & Infrastructure

SilverBullet is intentionally lightweight; a single binary (or Docker image) runs on any Linux, macOS, or Windows host. The application can be containerized with a minimal Alpine‑based image that mounts the content folder as a volume. For scalability, multiple instances can share the same file store behind a networked filesystem (e.g., NFS or SMB), and a reverse proxy (NGINX, Caddy) can handle TLS termination and load balancing. Because the data is file‑based, scaling horizontally requires careful coordination to avoid write conflicts; a simple lockfile or advisory locking mechanism is recommended.

Integration & Extensibility

• Webhooks: Developers can hook into file changes via a built‑in event bus, triggering external services (e.g., CI pipelines, chat notifications).
• API: A RESTful interface exposes CRUD operations on pages and objects; authentication can be delegated to a reverse proxy or integrated OAuth2 provider.
• Custom Widgets: Lua scripts can register UI widgets that render within the editor or sidebar, enabling dashboards, charts, or external API consumers.
• CLI Tools: The project ships with a CLI for batch operations (e.g., bulk tag updates, export to JSON), which can be scripted in CI/CD pipelines.

Use Cases

• Personal Knowledge Management: Developers who need an offline‑first, scriptable wiki for their notes and code snippets.
• Rapid Prototyping: Using Space Lua to generate UI components or data visualizations directly from Markdown, reducing the need for separate front‑end projects.
• Team Documentation: When combined with a shared file system, teams can collaborate on Markdown documents while keeping the data under version control.
• Embedded Documentation: Host SilverBullet in a Docker container behind an internal reverse proxy to provide lightweight, searchable documentation for micro‑services.

Advantages

SilverBullet’s blend of offline capability, scriptable extensibility, and file‑based persistence gives developers a powerful yet simple platform. Its MIT license removes licensing friction, and the lack of external dependencies means you can host it on any server without vendor lock‑in. Performance is boosted by the local IndexedDB cache, and flexibility comes from exposing a Lua sandbox that can interact with every object in the space. For developers who value control, privacy, and rapid iteration, SilverBullet offers a compelling alternative to commercial note‑taking or wiki solutions.