Architecture Overview

Architecture Overview

Language: English · 简体中文

LWC is a local-first Rust CLI organized around one rule: SQLite owns knowledge; every other representation is derived or deployment-local. This boundary lets Agents use richer retrieval and graph capabilities without making an optional service the source of truth.

Read this page when evaluating a change that crosses storage, indexing, graph, Agent integration, or recovery boundaries.

System view

Agent / human / script
        |
        v
Clap CLI dispatcher -------- stdio MCP server -------- AgentTarget installer
        |                           |                          |
        +----------- bounded commands and typed JSON --------+
                                    |
                                    v
                         canonical Store (SQLite)
                         Sources · Pages · links
                         ingest · tags · retrieval
                         operations · changesets
                                    |
             +----------------------+----------------------+
             v                      v                      v
      generated Markdown      document graph         search projections
      human-readable          Grafeo/SurrealDB        FTS5 + spans
                                    |
                                    v
                              durable Work

Project source files --------------------------> CodeGraph index
                                                separate, project-local

Command path

The binary has three front-door layers:

1. cli::definitions declares the public command grammar with Clap.
2. cli::dispatch resolves scope, enforces live/draft boundaries, opens the required store mode, and routes the command.
3. store, work, external_graph, codegraph, agent, mcp, trans, and view implement domain behavior.

Commands return structured JSON on standard output and structured errors on standard error. Human-readable text is kept inside fields rather than replacing the machine contract.

Hidden worker execution is an internal transport. Users operate it only through work list, status, watch, cancel, and resume.

Canonical plane

Each Wiki has one wiki.db. Canonical writes use SQLite transactions and update all inseparable records together:

• Source snapshot and pending ingest job;
• Page body, citations, provenance, links, search document, spans, and operation record;
• tag policy and membership;
• retrieval weights or query-fingerprint feedback;
• changeset state and inverse metadata.

Source content is immutable and content-addressed. Pages are maintained mutable knowledge. Their relationship is explicit through page_sources; neither representation silently replaces the other.

Store identity contains a stable store ID and a changing revision fingerprint. Changesets, checkpoints, spans, and concurrent restore checks use these identities to detect stale or mismatched state.

Derived planes

Search

Contentless SQLite FTS5 tables hold normalized Page, Source, passage, and sentence terms. Exact span records store UTF-8 byte ranges and content fingerprints. Reindexing can recreate this state from canonical documents.

Markdown

The .lwc/wiki/ tree is generated for people and Markdown-aware tooling. It is not an alternate write path. Materialization uses staged files and replacement semantics so a failure is recoverable without redefining canonical state.

Document graph

Grafeo and SurrealDB sidecars receive projections of canonical Page, Source, link, citation, and semantic-relation facts. Mutations append dirty document keys to durable Work. graph verify compares the selected sidecar with canonical projection keys and fingerprints.

CodeGraph

CodeGraph indexes checked-out project files, not Wiki records. LWC pins and verifies one runtime version in the user's global cache while keeping each project's database under .lwc/codegraph. It remains a separate evidence plane even though MCP exposes it through the same lwc_explore tool.

Deployment-local plane

The following state controls one installation rather than Wiki knowledge:

• .lwc/config.json and the global ~/.lwc/config.json;
• Work request and progress files;
• document-graph sidecars;
• CodeGraph runtime and project index;
• AgentTarget receipts and host configuration;
• generated Viewer assets embedded in the binary.

Checkpoint restore therefore replaces wiki.db, then rebuilds or requeues derived projections under the current deployment configuration.

Live and draft stores

A changeset is a sparse SQLite overlay bound to one live store and base revision:

.lwc/wiki.db                         live canonical store
.lwc/changesets/<name>.db           sparse draft records
.lwc/changesets/draft-<name>/        isolated Work and graph runtime

Draft reads compose live baseline with touched draft entities. Commit does not replace the whole live database; it validates fingerprints and merges one exact patch under the live write lock. This preserves unrelated live writes and supports a touched-entity inverse.

Read and write boundaries

Read commands open current-format stores read-only. A store that requires a supported migration is opened through the writable migration path before the requested command proceeds.

Mutations reject --scope all. Deployment-local configuration, Viewer, checkpoint, CodeGraph lifecycle, and conversion also reject changeset selectors when they cannot participate in the draft's atomic contract.

MCP deliberately stays read-only. Missing indexes become readiness guidance or typed unavailable states; an MCP request never downloads a runtime, enables a graph, or mutates memory.

Failure model

LWC distinguishes three outcomes:

1. No canonical write: validation, conflict, or lock acquisition failed.
2. Canonical success: the transaction committed and every required projection completed or was queued.
3. Canonical partial success: knowledge committed, but graph queueing, cleanup, or materialization failed.

The third case returns explicit fields such as canonical_committed or checkpoint_restored plus an exact recovery command. Retrying a higher-level operation is safe only when its documented idempotent recovery path says so.

Derived failure does not roll back valid canonical knowledge by pretending it never committed. Conversely, a successful Work does not prove the graph is consistent until verification passes.

Security boundaries

Architecture-level safeguards include:

• canonical path checks and symlink rejection for stores, drafts, Work, config, and sidecars;
• project-root containment for explicit project selection and CodeGraph paths;
• create-new or atomic replacement for owned files;
• secret scanning before Source ingest, conversion arguments, and selected integration writes;
• loopback-only, GET/HEAD Viewer routes;
• one read-only MCP tool with explicit project path validation;
• ownership receipts and marker-bounded edits for Agent hosts.

These controls do not make an untrusted local account safe. LWC assumes the user authorizes the current process to read the selected project and user-level integration files.

Component ownership

Component	Owns	Does not own
Store	Canonical knowledge and transactional invariants	External graph availability
Work	Durable execution state for long mutations	Canonical business decisions
External graph adapter	Projection, queries, and verification	Source truth
CodeGraph adapter	Runtime pinning and project code index boundary	Wiki memory
MCP	Bounded read-only exploration	Initialization or mutation
AgentTarget adapter	Official host files and LWC-owned fragments	UI-only settings or broad trust approval
Viewer	Local inspection	Editing, migration, or index construction
Trans adapter	Safe subprocess conversion	Automatic Source ingest

Design test

Before adding a capability, answer:

1. Which canonical record proves the fact?
2. Is the new state canonical, derived, or deployment-local?
3. What transaction makes inseparable writes atomic?
4. How is derived state rebuilt and verified?
5. What happens after canonical commit but before projection finishes?
6. Which scope and project boundary authorize the operation?
7. Can the same need be served by an existing Store, Work, or AgentTarget path?

If these answers are unclear, the change is not ready to cross the architecture boundary.

Next: Storage and data model