Synapse/docs/agent-guide/implemented/architecture/2026-08-24-logseq-runtime-and-engineering-guide.md

# Logseq Runtime and Engineering Guide

Status: implemented

This is a compact, source-verified engineering guide for the runtime areas that
were previously documented across docs/agent-guide. It was checked against the
repository on 2026-08-24.

The guide explains durable architecture, data flow, invariants, failure behavior,
and verification entry points. It intentionally omits implementation schedules,
branch instructions, temporary measurements, review snapshots, and product
research. Source code, tests, generated OpenAPI, and active subsystem
documentation remain the detailed contracts behind this guide.

## Problem

Engineering knowledge about the CLI, db-worker-node, db-sync, rendering,
outliner performance, search, and Graph View was distributed across plans and
reports. The useful content was mixed with proposed work, obsolete paths, and
time-sensitive observations. Engineers need one short technical map that
preserves the valid constraints without treating historical plans as current
contracts.

## Decision

### System model

Logseq uses different runtime processes. Within one local runtime, the worker
database is authoritative for graph state. On Desktop, a graph has at most one
active local writer daemon; remote db-sync storage is a synchronized copy, not a
second local writer.

| Runtime | Main responsibility | Persistent database |
| --- | --- | --- |
| Browser renderer | UI, editor state, worker client | None directly |
| Browser db-worker | Graph transactions and queries | SQLite through OPFS |
| Desktop renderer | UI and remote persistence client | None directly |
| Electron main | Window and db-worker-node lifecycle | Filesystem coordination |
| db-worker-node | Graph transactions, queries, sync, search | Filesystem SQLite |
| CLI | Command parsing, orchestration, formatting | Uses db-worker-node |
| db-sync Worker/DO | Remote graph access and ordered synchronization | D1/DO SQLite and R2 |

Important ownership rules:

- The worker database is authoritative for graph state.
- Desktop and CLI use the same graph directory, lock protocol, and
  db-worker-node runtime.
- The renderer must not create a second optimistic graph authority.
- Disk SQLite is the Desktop source of truth. OPFS export is not the Desktop
  primary persistence path.
- A graph must not have two active writer daemons.

Primary source map:

| Area | Source |
| --- | --- |
| Worker database and thread APIs | src/main/frontend/worker/ |
| Browser persistence | src/main/frontend/persist_db/browser.cljs |
| Desktop remote persistence | src/main/frontend/persist_db/remote.cljs |
| Electron runtime manager | src/electron/electron/db_worker.cljs |
| Shared daemon lifecycle | src/main/logseq/cli/server.cljs |
| Node daemon | src/main/frontend/worker/db_worker_node.cljs |
| CLI | cli/ |
| db-sync server | deps/db-sync/src/logseq/db_sync/worker/ |
| Renderer DB subscriptions | src/main/frontend/db/ |

### Worker platform boundary

frontend.worker.platform is the worker capability boundary. The required adapter
sections are:

- env
- storage
- kv
- broadcast
- websocket
- crypto
- timers
- sqlite

Vector and embedding capabilities are present when the runtime supports semantic
search.

The browser adapter uses OPFS, browser storage, browser WebSocket, and the worker
postMessage channel. The Node adapter uses filesystem paths, Node WebSocket,
Node crypto/storage primitives, and node:sqlite DatabaseSync.

Business namespaces should depend on frontend.worker.platform instead of testing
the host runtime repeatedly. Missing required capabilities fail during platform
validation. Optional capabilities may be absent only where the feature itself is
optional.

Interactive requests use frontend.worker.ui-request:

1. The worker creates a unique request id.
2. The host receives a typed request and payload.
3. The host resolves or rejects that exact request.
4. Cancellation rejects outstanding requests during graph/runtime shutdown.

Browser flows may request UI input. Headless Node flows must use explicit input
or return a useful error. New worker business logic should not call renderer
functions directly. One non-Node search progress path still uses
frontend.worker.state/<invoke-main-thread; do not treat that exception as a
general worker API.

### db-worker-node daemon

db-worker-node is a graph-bound localhost daemon. It starts the same worker core
used by the browser, installs the Node platform adapter, opens the requested
repo, writes graph and server-list metadata, and becomes ready only after worker
initialization succeeds.

Client-facing endpoints:

| Method | Path | Purpose |
| --- | --- | --- |
| GET | /healthz | Readiness, bound repo, process, owner, revision, host, and port |
| GET | /v1/events | Server-Sent Events from worker broadcasts |
| POST | /v1/import-db-binary?repo=... | Stream a SQLite database import |
| POST | /v1/invoke | Invoke a worker thread API with Transit arguments |
| POST | /v1/shutdown | Graceful close and process shutdown |

The daemon also answers CORS preflight requests. It binds to `127.0.0.1` on an
OS-selected port and has no remote-bind option.

Most thread APIs require the first argument to identify the repo. The daemon
rejects:

- a missing or blank repo with HTTP 400;
- a repo that differs from the daemon's bound repo with HTTP 409.

Only explicitly listed process-level APIs may omit the repo. This binding keeps a
client from accidentally sending graph work to another daemon discovered from
stale metadata.

#### Graph lock and ownership

The three discovery records have deliberately different scopes:

- `db-worker.lock` records `repo`, `pid`, `lock-id`, and `owner-source`.
- `server-list` records only `pid` and `port` pairs.
- `/healthz` reports `repo`, readiness status, host, port, pid, owner source,
  root directory, and runtime revision.

Neither the graph lock nor `server-list` is a readiness or revision authority.

Lifecycle behavior:

1. Resolve and validate the graph directory under the configured root.
2. Read the graph lock and remove it only when its owner process is absent.
3. Read `server-list`, discard entries whose pid is absent, and probe remaining
   entries through `/healthz`.
4. Spawn only when neither a discovered graph server nor a graph lock exists.
5. Require both a graph lock and a discovered server, then wait for readiness.
6. Reuse the daemon only when its reported revision matches the requester.
7. On revision mismatch, stop that exact server, start once, and verify the new
   revision; fail if stop, startup, or the second revision check fails.

A discovered process without the expected usable lock is not adopted as a valid
runtime; startup fails instead of returning an unowned endpoint.

Normal stop and restart operations respect owner boundaries. A proven revision
mismatch may replace the exact stale daemon across owner sources because the
requester cannot safely use it. Manual CLI cleanup remains limited to eligible
CLI-owned daemons.

#### Server list

root-dir/server-list is a discovery index of pid/port pairs. Mutations are
serialized through root-dir/server-list.lock.

The write protocol:

1. Create the lock with exclusive wx semantics.
2. Write lock owner metadata including pid, lock id, and timestamp.
3. Recover the lock only when its owner process is proven absent.
4. Read and normalize current entries while holding the lock.
5. Write a uniquely named temporary file.
6. Rename the temporary file over server-list atomically.
7. Remove the lock only when its lock id still matches.

Readers tolerate missing files and ignore malformed or duplicate entries. They
must still verify each entry through /healthz.

#### Electron graph switching and recovery

Electron owns graph-scoped runtimes in electron.db-worker. A window may bind to
one graph while another window keeps another graph runtime alive.

setCurrentGraph is metadata synchronization for the window graph path. It does
not release a worker. Runtime start/switch is handled by db-worker-runtime IPC,
and release is handled by explicit lifecycle or window close. Releasing from
setCurrentGraph can stop the newly selected runtime after a switch.

The renderer remote persistence client treats server-unavailable errors as a
runtime recovery signal. The current recovery threshold is one failed request.
Recovery is graph-scoped and must not silently switch the user to another graph.

The SSE client reconnects after 1000 ms by default and keeps scheduling another
attempt while the client remains connected; `disconnect!` stops that loop.
Request recovery is different: the first server-unavailable failure triggers at
most one recovery for the active runtime session. Session and repo checks stop a
stale recovery result from replacing the currently selected graph runtime.

#### Graph backups

Desktop and CLI share the graph backup layout:

~~~text
<root-dir>/graphs/<encoded-graph>/backup/<encoded-backup-name>/
  db.sqlite
  metadata.edn
~~~

Backup policy:

- Snapshot through SQLite backup APIs; do not copy a live database with a plain
  filesystem copy.
- Include db.sqlite only.
- Exclude WAL/SHM sidecars, search-db.sqlite, and client-ops-db.sqlite.
- Reserve the destination directory atomically.
- Add a numeric suffix when a generated backup name already exists.
- Write metadata only after the database snapshot succeeds.
- Remove an incomplete reserved directory on failure.
- Resolve shared-helper backup paths as children of the graph backup root.

metadata.edn records schema version, name, repo, source, creation time, and
database path. Retention is source-specific so automatic pruning cannot delete
manual backups.

Electron runs automatic backups hourly for active graph windows, throttles the
same source, and retains 12 automatic versions. Manual Desktop and CLI backups
are not subject to that automatic retention policy.

The shared ClojureScript helper validates path containment. The current OCaml
CLI `backup restore --src` and `backup remove --src` paths only trim the supplied
name and concatenate it below the backup root; they do not reuse that containment
validator. Do not treat those two `--src` arguments as safe for untrusted input.

Markdown mirror output keeps page-level identity but does not emit block
database ids as HTML comments.

### db-sync architecture

db-sync separates four concerns:

- index-level graph, membership, access, and E2EE operations;
- graph-scoped ordered sync in a Durable Object;
- semantic REST operations for external clients;
- asset storage and signed download access through R2.

Key files:

| Concern | Source |
| --- | --- |
| Entry and dispatch | deps/db-sync/src/logseq/db_sync/worker/dispatch.cljs |
| Sync route registry | deps/db-sync/src/logseq/db_sync/worker/routes/sync.cljs |
| Semantic route registry/OpenAPI | deps/db-sync/src/logseq/db_sync/worker/routes/semantic.cljs |
| WebSocket protocol codec | deps/db-sync/src/logseq/db_sync/protocol.cljs |
| Sync handlers | deps/db-sync/src/logseq/db_sync/worker/handler/sync.cljs |
| Semantic handlers | deps/db-sync/src/logseq/db_sync/worker/handler/semantic.cljs |
| Storage | deps/db-sync/src/logseq/db_sync/storage.cljs |
| Client sync | src/main/frontend/worker/sync/ |
| MCP and ChatGPT entry | deps/db-sync/worker/entry.mjs |

Graph-scoped sync requests use /sync/<graph-id>/... and are forwarded to the
corresponding Durable Object.

#### Sync HTTP routes

The graph-scoped route registry contains:

| Method | Internal path | Purpose |
| --- | --- | --- |
| GET | /health | Graph sync readiness |
| GET | /pull | Transactions after a server t |
| GET | /checksum/diagnostics | Incremental and recomputed checksum details |
| GET | /snapshot/download | Snapshot download |
| GET | /snapshot/stream | Framed snapshot stream |
| DELETE | /admin/reset | Administrative graph reset |
| POST | /tx/batch | Ordered transaction batch |
| POST | /snapshot/upload | Streaming snapshot upload |

Use the route registry for the exact method/path contract. Public dispatch adds
graph id, authentication, access checks, and Durable Object forwarding.

#### WebSocket protocol

Messages are JSON maps. Transaction payloads inside the maps are Transit
encoded. UUIDs are serialized as strings.

Client messages:

| type | Important fields | Result |
| --- | --- | --- |
| hello | none | hello with current t and optional checksum |
| ping | none | pong |
| presence | editing-block-uuid | broadcast presence update |
| pull | since | pull/ok with t, txs, and optional checksum |
| tx/batch | t-before, txs, optional client-revision | tx/batch/ok or tx/reject |

The server also broadcasts online-users, presence, and changed notifications.
Malformed JSON, invalid since values, and unknown types return an error message.

Transaction batches use optimistic ordering:

- t-before must be a non-negative number.
- t-before must equal the server's current t.
- snapshot upload must be complete before normal transactions apply.
- a successful logical batch advances t and returns tx/batch/ok.
- a stale request returns tx/reject with the current t.
- a partial failure reports the new t plus successful and failed transaction
  identifiers when available.
- peers receive one changed notification after the batch and checksum settle.

Clients must pull/rebase after stale rejection instead of retrying the same batch
blindly.

#### Semantic REST and MCP

The semantic API lives under /api/v1 and exposes operations for:

- graph discovery;
- pages and page references;
- blocks, recursive trees, and block moves;
- typed properties and batch property updates;
- journal capture;
- Task objects;
- tags and tagged objects;
- assets;
- graph search.

The semantic layer uses Logseq outliner and property semantics. It must not
implement mutations as arbitrary raw DataScript transactions.

Security and data rules:

- Every operation declares logseq/read or logseq/write OAuth scope.
- Graph access is checked before dispatch into the graph Durable Object.
- E2EE graphs fail closed because the server cannot interpret their content.
- Rate limiting happens before expensive Durable Object work.
- Property mutations use typed DB graph properties, not file-graph key:: text.
- Task creation uses the Task class and typed status/priority/date properties,
  not Markdown TODO syntax.
- Asset uploads are limited to 100 MB and require an exact size plus SHA-256
  checksum.
- The generated /openapi.json is the detailed external contract.

MCP is a thin integration over the semantic API. entry.mjs owns request wiring,
chatgpt_app.mjs owns app metadata, and chatgpt_asset_upload.mjs adapts asset
uploads. Do not create a second independent mutation API for MCP tools.

#### Authentication and E2EE state

Worker auth belongs in frontend.worker.state/*state under namespaced keys:

- :auth/id-token
- :auth/access-token
- :auth/refresh-token
- :auth/oauth-token-url
- :auth/oauth-domain
- :auth/oauth-client-id

frontend.worker.state/*db-sync-config contains transport configuration such as
:ws-url and :http-base. non-auth-db-sync-config strips auth-shaped keys before
storing transport config.

E2EE password rules:

- Never store plaintext passwords in cli.edn or db-sync config.
- Verify a supplied password against the encrypted private key before saving it.
- Do not overwrite a valid stored payload after a failed verification.
- Encrypt the persisted password with material derived from the refresh token.
- Browser storage uses the platform secret store.
- The Node platform prefers the OS keychain under the Logseq E2EE service.
- If keychain access fails, Node falls back to root-dir/kv-store.json.
- CLI E2E mode uses the KV store directly so tests do not mutate the keychain.
- Headless flows fail with a missing-password error and a command hint.
- Interactive browser/Desktop flows may request a password through ui-request.

CLI cloud tokens are stored separately in ~/logseq/auth.json. Runtime sync
receives auth state in memory.

#### Large operations

Large logical transactions must remain one ordered operation while bounding
individual allocations and requests.

Client upload behavior:

- frontend.worker.sync.apply-txs groups datoms without splitting an inseparable
  datom group.
- Upload requests target a 5000-datom cap; one inseparable group may exceed it.
- Chunks are sent sequentially and preserve logical order.

Server apply behavior:

- A large entry targets 500-item apply chunks; one inseparable group may exceed
  the target.
- Intermediate chunks suppress per-chunk checksum updates.
- The final checksum is updated from the complete logical transaction.
- The listener is installed and removed around the operation.
- Failure payloads preserve already successful transaction ids and the failed
  transaction id when known.

Do not promise full rollback across already committed chunks. Preserve explicit
partial-success reporting so clients can reconcile deterministically.

#### Checksums

logseq.db-sync.checksum owns the checksum algorithm. It normalizes eligible
entities into stable tuples and supports both full recomputation and incremental
updates.

Checksum comparison is meaningful only when local and remote transaction
positions are synchronized. The client records the latest remote checksum and
logs a mismatch only after that readiness condition.

Investigation sequence:

1. Record graph id, local t, remote t, local checksum, and remote checksum.
2. Query /checksum/diagnostics for the server recomputation.
3. Recompute the local checksum from the same logical graph state.
4. Compare normalized tuple diagnostics, not raw SQLite row order.
5. Replay a captured transaction with the scripts exposed by
   deps/db-sync/package.json when the incremental transition is suspect.
6. Distinguish a true state divergence from a stale t/checksum observation.

Snapshot upload may initialize a missing checksum only before transaction history
has advanced. It must not overwrite an existing different checksum.

#### Cycle repair utility

`logseq.db-sync.cycle` implements and tests reference-cycle repair for:

- :block/parent, cardinality one;
- :logseq.property.class/extends, cardinality many.

Its algorithm:

1. Collect entities touched by remote and local transaction reports.
2. Detect a reachable cycle with DFS across the configured attribute.
3. Prefer an edge whose current value differs from the corresponding value in
   the remote transaction report.
4. Retract one edge on the cycle.
5. For block parent, add a safe remote parent or page root when possible.
6. For class extension, prefer the remote reference set or Root fallback.
7. Repeat until stable, with a 16-iteration safety cap.

Repair transactions use `:outliner-op :fix-cycle`, disable undo generation, and
set `:persist-op? false`.

Current integration boundary: the client remote-apply path in
`frontend.worker.sync.apply-txs` repairs duplicate outliner orders but does not
call `logseq.db-sync.cycle/fix-cycle!`. The utility and its unit tests therefore
must not be described as active client-side cycle repair.

#### Schema and failure policy

D1 schema changes require SQL migrations in deps/db-sync/worker/migrations.
Runtime schema initialization is not a substitute for a migration.

db-sync should fail closed on invalid auth, graph access, E2EE semantic access,
stale ordering, invalid snapshots, and malformed transaction payloads. Do not
introduce defaults that hide corrupt state.

### Incremental rendering and outliner transactions

The worker commits graph state once and derives renderer state from the committed
transaction.

Current flow:

1. An outliner/thread API transacts in the worker.
2. frontend.worker.db-listener receives the complete transaction report.
3. render-affected-keys derives exact resource invalidations.
4. render-delta builds one renderer delta.
5. The worker broadcasts :sync-db-changes.
6. frontend.db.subs applies the graph-scoped revision.
7. React hooks read immutable snapshots from frontend.db.hooks.

#### Render delta contract

A delta contains:

- graph-id;
- rev, derived from the authoritative database transaction position;
- optional operation id;
- complete block replacements keyed by block UUID;
- deleted block tombstones with revision and previous db/id when available;
- child membership patches per parent;
- affected render-resource keys.

Every replacement block carries :block/tx-id. A block cannot be both replaced
and deleted in one delta.

Child patches contain base-rev and rev plus ordered remove/upsert operations.
Membership changes are derived from:

- :block/parent;
- :block/order;
- :block/closed-value-property;
- :logseq.property/created-from-property;
- :logseq.property/deleted-at.

The renderer ignores a whole delta when its graph differs from the active graph
or its revision is not newer. For child patches, a mounted slot whose base
revision cannot be reconciled is marked stale and reloaded instead of being
merged speculatively.

#### Subscription store

frontend.db.subs owns one immutable external store. Important resource
identities include:

- [:block uuid]
- [:children parent-uuid]
- [:resource resource-key]

Subscriptions watch exact keys. Applying a delta updates cached blocks and
children, marks affected resources, and notifies only slots whose snapshot
changed.

Render-resource computation is registered in
frontend.worker.handler.render-resource.engine. Families include basic graph
lookups, property resources, views, and queries. The registry and
render-affected-keys must evolve together: every cached resource needs an exact
invalidation rule.

Checksum updates, db-sync persistence, Markdown mirror work, and search-index
updates run after the graph transaction commits. Each registered listener is
wrapped so synchronous or promise failures are reported through
`:capture-error`; they do not roll back the committed graph transaction.

#### Outliner performance guardrails

Outliner mutations use worker-owned transactions and publish their committed
result through the renderer delta path. Do not add a second optimistic block
tree or publish the same mutation independently from both a command response and
the DB listener. Page-window APIs should transfer the requested window, not a
full page, and graph-open work must not add graph-wide GC or `VACUUM`.

Useful transaction-pipeline measurements that are already logged include:

- performance id, outliner operation, and transaction count;
- renderer pipeline, delta construction, and broadcast time;
- checksum, persistence, sync-main, and registered-handler time;
- total listener time.

These measurements are diagnostics, not a fixed latency guarantee.

### CLI engineering guide

The shipped CLI is implemented in OCaml and compiled with Melange:

~~~text
cli/ OCaml
  -> Dune/Melange
  -> Vite bundle
  -> cli/_build/default/dist/logseq-cli.js
  -> scripts/stage-cli-runtime.mjs
  -> static/logseq-cli.js
~~~

db-worker-node remains ClojureScript and is bundled separately to
dist/db-worker-node.js. There is no shadow-cljs logseq-cli target.

CLI source map:

| Concern | Source |
| --- | --- |
| Entry/orchestration | cli/lib/cli.ml |
| Command ids | cli/lib/command_id.ml |
| Registry/help/options | cli/lib/command_registry.ml |
| Parsing | cli/lib/cli_parse.ml |
| Actions | cli/lib/cli_action.ml |
| Worker transport | cli/lib/transport.ml |
| Daemon lifecycle | cli/lib/server_runtime.ml |
| Graph/import/export/backup | cli/lib/graph.ml |
| Sync | cli/lib/sync.ml |
| AgentBridge | cli/lib/agent.ml |
| Platform effects | cli/lib/platform/ |
| Public command reference | docs/cli/logseq-cli.md |

cli/spec contains interfaces and cli/test contains unit/parity tests. The CLI
uses the existing CLJS daemon; do not duplicate the worker database or sync
implementation in OCaml.

#### Configuration and output

With the default root, runtime files may include:

~~~text
~/logseq/
  cli.edn
  auth.json
  kv-store.json
  server-list
  graphs/
~~~

Configuration precedence is global flag, then environment variable, then
cli.edn. Auth tokens and E2EE passwords are not CLI config fields.

Output modes:

- human is display-oriented and may truncate table titles by display width;
- json and edn preserve full values for scripts;
- namespaced keyword keys retain namespace/name form in JSON;
- UUIDs become strings in JSON;
- verbose and profile diagnostics go to stderr;
- normal structured stdout must not contain human warnings;
- sync progress is disabled by default for structured output unless explicitly
  requested.

Executed commands are normalized internally to `Cli_result.t`, with status,
data or error, optional command id, output renderer, and optional exit code.
Human output may be a table or message; JSON and EDN serialize structured
results. `skill show` deliberately renders the skill body as raw human text.

#### Data operations

The CLI exposes list, show, search, query, upsert, move, and remove commands.
Important shared rules:

- Human list titles are CJK-aware and truncate by display width, not byte count.
- Structured list output never uses human truncation.
- Selectors must be unambiguous; commands reject conflicting id, UUID, ident,
  name, and page options.
- list node tag/property filters use all-of semantics.
- Block and page references are rendered from UUID-backed graph data.
- show resolves nested block references with a depth cap.
- show page hierarchy is explicit and does not replace normal page content
  display.
- Library is a special hierarchy root, but ordinary page hierarchy uses the
  same bounded traversal and cycle protection.
- Mutations use worker outliner APIs rather than raw database editing in the
  CLI.

SQLite export asks the worker to write the snapshot directly to the destination
path. EDN export forwards validated graph export options. SQLite import has a
top-level missing-graph check; EDN import may target an existing graph.

Current limitation: `graph backup restore` imports a SQLite backup but is not
included in the CLI's top-level missing-graph check. It must not be documented as
rejecting an existing destination until that constraint is implemented.

#### Sync behavior

CLI sync reuses worker-side sync logic:

- upload resolves or creates a remote graph identity before snapshot transfer;
- download starts a create-empty daemon and refuses a non-empty target;
- download uses a long-running command timeout;
- progress uses /v1/events and :rtc.log/download;
- asset download validates the asset entity and local checksum before enqueue;
- a valid local asset skips the remote request;
- a checksum mismatch requests a new download;
- sync config accepts transport keys only;
- E2EE password verification and storage remain worker-owned.

doctor validates the daemon bundle, root permissions, running server readiness,
and revision compatibility. When startup reports missing bundled modules, rebuild
db-worker-node and verify every asset in dist/db-worker-node-assets.json.

#### AgentBridge

cli/lib/agent.ml owns graph-scoped AgentBridge routing.

Implemented routing constraints:

- one bridge lock exists per graph and agent name;
- the agent name comes from configuration or hostname and must be non-empty;
- one master Codex session is started and resumed for task and comment dispatch;
- a task is routable only when it has a stable UUID, the Task class, TODO status,
  the matching assignee, and no `:logseq.property.agent/session-id`;
- an ancestor task session id is passed to the master as inherited routing
  context for descendant tasks.

Prompt templates from the AgentBridge registry are loaded and validated at
startup, and invalid custom templates are replaced with defaults. The current
dispatch path discards that returned template set and constructs hard-coded
master prompts instead. Custom registry templates therefore must not be
documented as affecting dispatched prompts until the dispatch path consumes
them.

The generated master instructions say that only the master may write graph
results, subagents are read-only, and a launched child session id must be saved
on the task. Those are prompt-level policies, not enforcement by the OCaml
bridge, so they must not be presented as runtime guarantees.

Keep graph queries, lock ownership, task routing, prompt construction, and
external process effects separately testable.

### Vector search

Desktop vector search uses:

- Electron embedding server:
  src/electron/electron/embedding_server.cljs;
- default sentence-transformer model: all-MiniLM-L6-v2;
- embedding dimension: 384;
- vector context version: 3;
- zvec-backed Node vector index;
- SQLite keyword search plus vector results.

Each searchable block keeps at most one vector document, keyed by block UUID.
Both indexes derive their text from that block's search title; they do not
concatenate parent, sibling, or child context. SQLite FTS stores a normalized
form for ordinary blocks. The vector document embeds and retains the
pre-normalized title for ranking context-term boosts.

Constraints:

- Do not multiply vector count with rolling windows.
- Do not add parent/sibling traversal to full rebuild or incremental indexing
  without a measured need and an explicit invalidation model.
- Preserve exact keyword matches ahead of weak vector hits.
- Current vector search returns at most 10 vector candidates and requires score
  greater than 0.5.
- A completed vector rebuild writes model id, dimension, and context version to
  index metadata. The current rebuild decision checks the SQLite search index
  `PRAGMA user_version` or an explicit force flag; it does not compare the
  persisted vector metadata on open. Do not claim automatic metadata-mismatch
  rebuild until that check exists.

Incremental indexing derives affected searchable entities from the transaction.
It intentionally does not reindex adjacent siblings merely because a sibling was
reordered, and it does not expand a moved block update to the new parent. Page
hierarchy changes do reindex descendant pages whose indexed titles depend on the
hierarchy.

### Graph View

Graph View is a relationship browser built from worker graph data and rendered
with Pixi.

Source map:

| Concern | Source |
| --- | --- |
| Global UI and settings | src/main/frontend/components/graph.cljs |
| Page/block sidebar graph | src/main/frontend/components/page.cljs |
| Worker graph builder | src/main/frontend/worker/graph_view.cljs |
| React/Rum bridge | src/main/frontend/extensions/graph.cljs |
| Pixi renderer | src/main/frontend/extensions/graph/pixi.cljs |
| Layout and visibility logic | src/main/frontend/extensions/graph/pixi/logic.cljs |
| Styling | src/main/frontend/extensions/graph.css |

The renderer receives plain nodes and links. The worker emits string endpoint
ids and deduplicates links by directed endpoint pair. A later nonblank label can
replace an earlier label for the same pair, and class-extension links carry an
explicit `class-extends` edge type.

Relationship sources:

- :block/tags;
- :block/refs, lifted to owning pages where appropriate;
- user ref properties, labeled with the property title;
- :logseq.property.class/extends;
- :block/parent for page hierarchy in all-pages mode.

Global modes:

- tags-and-objects is the default;
- all-pages renders the visible page relationship graph.

tags-and-objects excludes property definitions, hidden/recycled entities,
excluded entities, and core internal tag classes. It renders tag/class nodes,
their objects, class-extension links, and visible ref-property links.

all-pages excludes hidden/recycled pages and internal property pages. Journals,
built-ins, excluded pages, and orphans are controlled by options. The large-graph
path activates at 10,000 page-name datoms, bounds visible ref links to 20,000,
then appends property, parent, and extension link tuples before applying a
20,000-link cap to the combined sequence. Because ref links come first,
structural links are not guaranteed to survive when the cap is exhausted.

The page graph centers on a page and includes references, mentions, tags, class
extensions, and selected second-order relationships. The block graph centers on
a block and connects incoming/outgoing referenced pages. Both use the same Pixi
page-mode renderer.

Renderer invariants:

- visible-node sets filter rendered nodes and links independently from the
  source graph data;
- label selection is bounded and screen-cell based to reduce overlap;
- all-pages and tags-and-objects share the Pixi renderer plumbing;
- the renderer exposes explicit visibility updates and destroys its label,
  edge-label, and application resources during cleanup.

Per-repo settings are stored under logseq.graph.settings.<repo>. They cover view
mode, selected tags, depth, link distance, grid layout, journal visibility, and
open settings groups. Time-travel cutoff is session state and is not persisted as
the graph's initial filter.

### Frontend state and UI dependencies

frontend.state remains the primary application state namespace. Focused modules
such as frontend.graph-tab own selected domains, but there is no general
src/main/frontend/state/ facade tree. Add a focused state namespace only when it
has real ownership, not to mirror a historical split plan.

The UI stack uses Base UI and Tailwind 4. Read package.json and current component
usage before changing dependency or styling conventions.

### Engineering workflow

Before changing a subsystem:

1. Read root and directory-specific AGENTS.md.
2. Locate the owning source, its callers, and its tests.
3. Confirm runtime boundaries: browser, renderer, Electron, Node worker, CLI, or
   server.
4. Write or update the narrowest behavior test.
5. Preserve one authoritative data path.
6. Fail fast on invalid internal state.
7. Remove obsolete paths instead of adding compatibility fallbacks.
8. Run focused tests before broad verification.

Useful commands:

~~~sh
# Repository lint and unit tests
bb dev:lint-and-test

# One unit test
bb dev:test -v <namespace/testcase-name>

# Already-compiled CLJS namespaces
bb dev:run-test-namespaces -n <namespace>

# CLI
(cd cli && opam exec --switch=<compatible-ocaml-switch> -- dune runtest)
pnpm cli:release
pnpm db-worker-node:release:bundle
bb -f cli-e2e/bb.edn test --skip-build

# db-sync
pnpm --dir deps/db-sync test
pnpm --dir deps/db-sync test:chatgpt-app
pnpm --dir deps/db-sync test:large-op-128m

# Agent document validation
spec-dev-tool check --all
~~~

Use docs/cli/logseq-cli.md for the current CLI command reference and generated
OpenAPI for the current semantic API contract.

## Alternatives considered

### Keep the original plans as the technical reference

Rejected because proposed steps and old file paths are indistinguishable from
current behavior during search.

### Duplicate every current source contract in prose

Rejected because exhaustive route, command, and schema duplication would become
stale quickly. This guide records durable concepts and points detailed contracts
to executable registries and tests.

## Consequences

The guide preserves useful architecture, protocol, data-flow, performance, and
debugging knowledge in one document. Historical task sequencing, temporary
benchmarks, and obsolete proposals are intentionally absent.

The guide is concise enough to read as an orientation document, but engineers
must still inspect the named source and tests before modifying behavior.