Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

System Overview

Lapis Notes is a layered Svelte application that reproduces a large part of the Obsidian runtime model across shared web and desktop hosts. The current source tree is browser-first, and the approved product targets are a web/PWA host and an Electron desktop host. The key design choice is that the workspace app does not own most domain behavior; it mounts the renderer shell, creates the root App instance, and delegates to runtime services and plugins.

The decision to adopt Electron as the first-party native desktop shell is recorded in ADR-003: Electron-First Desktop Shell.

Layer Diagram

user input
  → host shell (web/PWA or Electron desktop)
     → @lapis-notes/workspace (renderer shell)
        → @lapis-notes/api (runtime kernel)
           → Vault, Workspace, Configuration, Commands, Metadata, Plugins
        → @lapis-notes/ui (design system)
        → packaged feature plugins (markdown, search, bases, ...)
        → community plugins from /.obsidian/plugins

The approved cross-runtime plugin direction is recorded in ADR-001: Plugin Runtime Rework (desktop runtime target superseded in part by ADR-003).

Layers

LayerPackageRole
Monorepo rootpackage.json, pnpm-workspace.yamlBuild orchestration. PNPM workspaces with pnpm 10.12.3.
Runtime kernelpackages/apiApp model, workspace tree, storage abstractions, plugin lifecycle, commands, settings, metadata cache, editor/view infrastructure, event system, and compatibility surface.
Design systempackages/uiReusable Svelte components wrapping Bits UI, paneforge, svelte-sonner, and TanStack Table. Tailwind-styled. No domain logic.
Application shellpackages/workspaceVisible renderer shell. Boots the web/PWA host directly today and remains the shared renderer layer for both web and desktop hosts.
Feature pluginspackages/plugins/*Markdown editing (including inline list callouts), SQLite/AppDatabase-backed full-text search, structured data views (Bases/PEaQL), grammar checking (Harper WASM).
Desktop shellpackages/desktop-electronFirst-party Electron desktop host. Owns app lifecycle, native window behaviour, IPC command handlers, and desktop-only runtime adapters.

Technology Stack

ConcernTechnology
UI frameworkSvelte 5 (runes: $state, $effect, $derived)
LanguageTypeScript
BuildVite
StylingTailwind CSS 4 with oklch color system
EditorCodeMirror 6
Package managerpnpm 10.12.3 (workspace protocol)
VCSJujutsu (colocated with Git)

Architectural Principles

  1. App owns services. The App class is the single root that constructs and holds the workspace, vault, plugin manager, commands, configuration, metadata cache, and all registries.

  2. Plugins are first-class. Built-in features and community plugins use the same Plugin base class, runtime states, and PluginManager. Core plugins are registered before discovery, then activated through the same manager as community plugins.

  3. File-first data flow. Storage updates propagate into metadata indexing, then into higher-level features like search and views. The vault is the source of truth.

  4. Event-driven. Almost all classes extend EventDispatcher (wrapping EventEmitter3). Changes propagate via typed events rather than direct mutation observers.

  5. Adapter-driven storage. OPFS is the default for new browser-local vaults. File System Access API covers user-selected real folders in web runtimes. Native hosts can add adapters without rewriting the runtime kernel.

  6. Thin shells. The workspace app is composition code. Host shells stage the runtime, render the layout, and delegate domain behavior to the API layer and plugins.

  7. Obsidian compatibility. The API surface intentionally mirrors Obsidian’s plugin API. compat.ts, parity tests, and the moment shim maintain upstream compatibility. Community plugins can require('obsidian') and get @lapis-notes/api.