The architecture in one pass
Univer Runner is an offline-first spreadsheet collaboration stack that joins local editing, Git-shaped workflow, hosted review, and remote workbook sync.
6 min read
System definition
Offline-first collaboration stack
The product is not only a local CLI or a review site. It links local spreadsheet editing, structured review, and remote workbook progression.
Primary design rule
Truth ownership beats menu shape
Boundaries are drawn around who owns durable state and state transitions, not around which command seems convenient in the UI.
Useful mental shortcut
Shells orchestrate, kernels own
App shells handle entry points, presentation, and process lifecycle. Kernel packages own contracts, data models, and final interpretation.
What this page explains
This page gives the shortest complete model of the system. It tells you what the product is, which layers hold durable truth, and why the architecture is cut the way it is.
If you only read one page before evaluating the stack, read this one first. The rest of the docs expand the same model from different angles.
One-sentence definition
Univer Runner is an offline-first spreadsheet collaboration stack for agents and humans, with Git-shaped review workflow and remote workbook replay.
The five layers of truth
The architecture becomes much easier to reason about when you read it as five separate sources of truth with different owners.
1. Workspace truth
workspace-substrate
Owns local workbook entries, workspace paths, local change batches, and origin sync state under `.agent-sheet`.
2. Repo truth
sheet-git-kernel
Owns repo objects, workflow truth, review sessions, replay runs, and pull projections under `.sheet-git`.
3. Hosted review truth
sheet-review-core
Owns reviews, revisions, deliveries, handoffs, comments, and hosted projections for Bob's review experience.
4. Sync and replay policy
git-shaped-sync-core
Owns readiness checks, pull decisions, replay planning, and changeset transform policy without pretending to own persistence.
5. Runtime seam
univer-runtime-sdk
Owns the stable boundary that lets shells attach to the execution runtime safely on Node and child-process bridges.
Shells and kernels serve different jobs
App shells
Entry points and orchestration
agent-sheet, sheet-git, review-host, apps/univer-runner, and qa-harness expose commands, transport, presentation, and lifecycle control.
Kernel owners
Truth, contracts, and state transitions
workspace-substrate, sheet-git-kernel, sheet-review-core, git-shaped-sync-core, and univer-runtime-sdk own the durable model behind the shells.
- Use the shell to find the entry point a user touches.
- Use the kernel owner to decide who has the final say over data structure and lifecycle.
- Treat command names as a convenience layer, not as architectural authority.
Why the split matters
The system would be easier to name if it were grouped by features like `file`, `review`, or `origin`. It would also be harder to maintain.
- A feature-menu split would scatter durable truth across unrelated commands and force maintainers to cross boundaries constantly.
- Truth ownership keeps local editing, hosted review, and remote authority distinct, so comments, approvals, and replay state do not collapse into one blurred model.
- The split also protects the product story: local work can exist without hosted review, and hosted review can close without executing origin replay.