Roam Research popularized networked note-taking — daily journals, bidirectional links, blocks you can refactor anywhere — but your knowledge base lives on someone else’s cloud, behind a subscription, in a format you cannot grep. Logseq answers that pain with a different bargain: the same outliner model, but your graph is stored on your own disk, and the entire application that manages it is open source. The current database version goes further than “plain files on disk”: a graph is a single SQLite database you can back up with one file copy, while Markdown export remains a derived, human-readable projection you can generate on demand.

Two diagrams in this post map that bargain onto the actual source tree. The overview traces the life of a keystroke: editor handler → outliner op → DB worker → in-memory Datascript → SQLite file, and back to the screen as immutable snapshots. The detail diagram adds the boot sequence, the schema and DataScript layer, the persistence backends (OPFS in the browser, files on the desktop), the query engine, and the plugin/SDK surface.

Reading this tour you will learn how a Lisp dialect (ClojureScript, compiled to JavaScript by shadow-cljs) runs a serious desktop app; why every paragraph you type is really an EDN datom; how the team moved graph ownership out of the renderer into a dedicated worker thread; how Datalog — not SQL, not a REST API — powers advanced queries; and what changed when Logseq migrated from Markdown-folder graphs to the SQLite-backed DB version. Every symbol cited below was verified against the master branch of logseq/logseq.

Logseq overview architecture: editor handlers, outliner ops, db worker, Datascript and SQLite storage, query engine

Overview: a keystroke crosses three boundaries — renderer to op layer, op layer to db worker, worker to SQLite — and returns as a snapshot diff.

Reading the overview from left to right:

Logseq detailed architecture: startup, outliner ops, db worker, DataScript schema, SQLite persistence, query engine, plugin SDK

Detail: the same flow with boot, schema, persistence backends, queries and the plugin SDK included — node labels name real namespaces you can open on GitHub.

Why Every Note Is a Datom

Logseq’s core data model is not “pages containing text” — it is a graph of entities whose state is a set of EDN datoms: entity, attribute, value, transaction tuples held in Datascript, an in-memory database that implements the Datalog logic language. The outliner layer validates blocks against an explicit map of the fields that make a block a block: :block/uuid, :block/order, :block/parent and :block/page (block-map, L57). Nesting an outline is literally writing :block/parent datoms; reordering is rewriting :block/order. The same file’s save-block, L672, insert-blocks, L1099 and delete-blocks, L1395 are the primitive verbs of the whole app — everything else, from templates to task lists, compiles down to them.

Because the model is a database, features that other apps bolt on with string matching become queries. “All properties of this page” is an avet-index datom scan: get-all-properties, L42 reads :block/tags datoms directly. Breadcrumbs are a parent walk: get-page-parents, L47. This is the block graph model that made outliner tools famous, expressed as data rather than as a document format — the same philosophy we examined in the Node source tour, where module structure is likewise the primary data, except here even your notes are queryable facts. The batch-txs state, L4 in the outliner dep is where collected ops wait to become one transaction.

The DB Worker Split: Why the Renderer No Longer Owns Your Graph

The most consequential recent decision in this codebase is architectural, not feature-wise: the graph database lives in a dedicated worker thread, and the renderer holds only immutable snapshots. The worker’s entrypoint (init, L30) initializes the database core and exposes it over Comlink; the renderer-side subscription layer calls itself “Immutable renderer snapshots loaded from the worker-owned graph database” (ns docstring, L2) and warms an LRU cache of twenty thousand slots (warm-cache-size, L11) through batched loads like <load-block, L55.

The write path mirrors the read path. The frontend transact namespace serializes each repository’s mutations by chaining promises (enqueue-outliner-mutation!, L26) before transact, L162 dispatches the request; when the worker returns, deltas are applied to the renderer under react-dom/flushSync (publish-worker-response!, L147) so the caret never visibly lags. This split is why heavy operations — full-graph queries, schema restore, undo grouping — stopped janking the editor: they are worker-side by construction. The project records these decisions as ADRs, and the worker also owns undo/redo semantics per those documents.

Startup follows the same ownership rule: restore-graph!, L11 opens the graph “from SQLite” (docstring, L12), fetches the schema through the persistence backend, resolves sync conflicts, and only then resets renderer subscriptions. The renderer never loads raw datoms itself — it asks the worker.

Queries: From Query Blocks to Datalog

Logseq ships two query tiers, and both compile down to the database the worker owns. The DSL tier is what you write in query blocks on a page: the renderer namespace is explicitly a thin wrapper, “Query execution belongs to the db worker” (ns docstring, L2); query, L40 dispatches thread-api/query-dsl-query, and the custom-query variant, L52 handles the advanced form.

The advanced tier is real Datalog. The guard require-datalog-query!, L46 rejects anything that is not a proper query vector starting with :find (the :find check, L50), and the namespace titles itself the handler for “custom queries a.k.a. advanced queries” (ns docstring, L2). That means the full expressiveness of Datalog — rule bodies, joins across :block/parent chains — is available inside a note. This is the quiet superpower of storing notes as datoms: a “query” is not a plugin feature, it is the native interface of the storage engine, and Logseq just picks the executing thread.

From Plain-Markdown Folders to SQLite Graphs

This section is the build-facts record of Logseq’s biggest migration. The classic released Logseq — still what most users run — treats a folder of Markdown and Org files as the source of truth: files are parsed by the mldoc parser (a separate Logseq project wrapped in ClojureScript, “taking and returning edn” only, logseq.graph-parser.mldoc, L2) and the AST is turned into transactions during import (graph-parser.extract docstring, L2). In that world, Datascript was rebuilt by re-parsing your files at startup, and sync meant file syncing.

The DB version on master inverts that: the source of truth is a SQLite file, addressed as get-db-full-path, L49 mapping a graph to its db.sqlite, and Datascript datoms persist through a storage table with (addr, content, addresses) rows created by create-kvs-table!, L10 for use with datascript.storage (docstring, L11). Fresh graphs are stamped out by schema helpers in logseq.db.sqlite.create-graph, L2 — built-in classes, properties and typed property values — and graph-kind checks lean on db-version-prefix, L308. The README marks the DB version beta while mobile and real-time collaboration mature (README, L71), and the dependency list wires the pieces together: the Datascript fork (deps.edn, L10), the outliner library (deps.edn, L45) and the db-sync library (deps.edn, L46).

Markdown survives, but demoted to a projection. ADR 0016 specifies an Electron-only mirror that writes derived Markdown under mirror/markdown/journals/ and mirror/markdown/pages/ (ADR 0016) — with the explicit rule that “the DB remains the source of truth” and mirror files feed back into nothing. If you want to understand how a durable local store can back an editor, the SQLite engine behind this design is itself worth a source tour.

Plugins and the Electron Shell

The extension surface is a second ClojureScript namespace reserved for third parties: logseq.api, L2 is documented as “Logseq API for plugins usage” and exports dozens of hooks — slash command registration (register_plugin_slash_command, L53), storage files, user settings, UI items. The host installs during boot via handler.plugin/setup!, L1341. DB-version-specific plugin calls live in logseq.api.db-based, L2 (“DB version related fns”), which routes page and property mutations through the same outliner core the editor uses — plugins get no side door into the database, and block APIs even namespace their properties (plugin.property prefix, L17) to keep plugin data distinguishable from user data. Compared with the compiler-checked, type-first approach we covered in the TypeScript source tour, this is a runtime-gated API: flexible for authors, stricter at the boundary.

On the desktop, the same ClojureScript bundle runs inside Electron. The renderer talks to the main process through electron.ipc/ipc, L28, which serializes payloads as transit strings before calling window.apis.doAction (doAction call, L33) — one typed channel instead of dozens of ad-hoc bridges. The main process owns filesystem primitives (native db.sqlite files, plugin directories, the Markdown mirror), while all content logic stays in the worker per the ADR.

Honest Limits

  • Master is the DB-version branch. The SQLite graph, worker split and mirror ADR describe current master; the classic file-version code paths largely live in release branches and history. Treat master as fast-moving — the README itself steers stability-seekers elsewhere.
  • DB version is beta. The README says data loss is possible and recommends backups; real-time collaboration is in alpha. The sync libraries exist in-tree (db-sync dep, L46) but the surrounding product surface is explicitly unfinished.
  • The Markdown mirror is one-way. Editing mirrored files does not update the graph, per ADR 0016; it is an export, not round-trip sync, and browser/mobile builds do not get it.
  • Datascript is still in memory. Durability comes from the SQLite storage layer, so very large graphs trade RAM for query speed; the kvs-table design (create-kvs-table!, L10) is the boundary where that trade is managed.
  • Docs drift. src/main/frontend/persist_db/README.md still describes the older in-memory mental model, so older tutorials can disagree with newer code about where the database lives.
Watch PyShine on YouTube

Contents