Architecture: four layers and objects

One system of four layers of responsibility, the core's exact place, the list of objects, and the main relationships between them.

The system is divided into four layers, each with its own owner. The last column is what matters for you: it says what a layer must not do—that’s where the boundaries run that must not be crossed when embedding.

Layer	Owner	Responsibility	Must never do
Your application	You	Users, permissions, the document card, versions, audit, approval processes. Document management here is just one case: it could just as well be an accounting system or an industry platform.	Doesn’t need to know the internal structure of the XLSX file.
The editor shell	Us, under your brand	Shows the editor, gathers the user’s intent, displays the response.	Never computes formulas and never changes the file itself.
The operations contract	The shared boundary both of us are responsible for	Describes commands, results, refusals, revisions, and capabilities.	Doesn’t depend on exactly where the core runs.
The Rust core	Us	The sole owner of the workbook’s meaning: computation, changes, history, saving.	Never manages the document card or your users.

Exactly where the core runs

The core is neither a server nor a screen. It’s a portable compute module: in the browser the same code runs inside the page (WebAssembly), in the desktop app or on a server—as an ordinary executable. The way it’s launched changes; the meaning of the workbook and the operations contract stay the same.

The shell — what the user sees, and the call sequence.
Operations contract—commands and responses of a known shape.
The core — a single model of the workbook and the operations on it.

Objects and relationships

Object	What it contains and knows	Lifecycle
Integration session	The document identifier, the user’s permissions, the product’s settings.	Created by your system when the editor opens.
Workbook session	The open workbook, the current revision number, the edit history, the execution mode, and the save state.	Lives from open to close; separate from every other workbook.
Workbook	Sheets, names, styles, settings, relationships, and the file’s utility parts.	Loaded from the file and changed only by the core.
Sheet	Cells, rows and columns, tables, objects, and print settings.	Identified not by name but by an internal key: renaming the sheet doesn’t change the key. But when exporting to another format the keys are rebuilt, so you can’t store the key as a permanent identifier in your database—take it from the open response.
Viewport	Only the visible part of the sheet, and information about it.	Changes on scrolling and zooming; it’s never the whole workbook.
Operation, also known as intent	The action, its parameters, the expected revision number, and constraints.	One request through the operations contract.
Result and event	The new state, exactly what changed, a warning or a refusal, and the data to display.	Arrive at the shell and your application after every operation.
Saved file	The file’s content, its format, and information about the save.	Goes into your document management system as a new version.

Main relationships

Integration session creates and constrains → workbook session
Workbook session owns the state → workbook, revision number, edit history
Workbook hands outward only what’s needed → viewport
Operation checks the revision and changes → workbook session
Save creates → the finished file → a new version in your system

What happens from opening the workbook to saving it — Lifecycle.
What the core can do next to Excel — the capability map.
Your first project — Quick start.