Application architecture
Understand the responsibilities of Web SDK, Server SDK, and AI SDK and how to combine them in an application.
Univer is a toolkit for building Office applications in which humans and AI Agents operate the same content. A Univer application can provide a human-facing Web interface, an AI Agent-facing CLI, and a Server shared by both, or use only the components it needs.
SDK family
| Component | Runtime | Primary SDK | SDK provides | Application owns |
|---|---|---|---|---|
| Web | Browser | Web SDK | Interactive Office display and edit | UI, product interactions, browser integration |
| CLI | Node.js | AI SDK | AI Agent-facing inspection and editing | AI Agent workflows, tool calls, and task bounds |
| Server | Node.js | Server SDK (Collaboration, Exchange) | Self-hosted collaboration and Office file import/export | Application APIs, identity, permissions, file storage, deployment |
Documentation is organized into Web SDK, Server SDK, and AI SDK, covering editors, collaboration and file exchange services, and AI Agent content operations.
The AI SDK reuses headless content capabilities from the Web SDK. These components identify the primary developer entry point and runtime placement, not three independent technology stacks or complete products that can be deployed without application code.
Integrate file import and export
The Server SDK module @univerjs-pro/exchange-node converts between Office files and Univer document data.
Your application integrates the conversion module and provides upload, conversion, and download APIs.
Web SDK handles the browser interactions, while a CLI can call the conversion module in Node.js.
Browser configuration remains in each product’s Web SDK documentation.
- Without collaborative editing: convert a file into a document snapshot, then open and edit it in the browser. To export, pass the latest snapshot to the conversion module to generate a file. This flow needs server-side conversion but does not require a collaboration service.
- With collaborative editing: save the imported data as a collaborative document. Web and AI SDK operate on the same content through its document ID. Before exporting, synchronize current edits, then read and convert the latest document data.
For file conversion alone, use Exchange in a local Node.js process or a remote service. Neither AI SDK nor collaborative editing is required. See File exchange integration for the application flow and Office file import and export for using the conversion module.
Deployment shapes
| Shape | Web | CLI | Server | Intended scope |
|---|---|---|---|---|
| Local app | Local browser/desktop UI | Local process | Local process | Desktop Office with a local AI Agent |
| SaaS app | Browser | User device/cloud AI Agent | Remote service | Multiple users and central ops |
| Web + Server | Browser | — | Local or remote | No AI Agent-facing surface yet |
| Web-only | Browser/desktop UI | — | — | Local, single-user, non-collab edit |
Components can run on one machine or span client devices and cloud infrastructure. Placement does not change their responsibilities. Whenever a Server exists, Web and CLI use it to access shared content and product capabilities.
Choose an entry point
| Goal | Start here |
|---|---|
| Embed an Office editor in a Web app | Web SDK documentation |
| Add Office file import/export to an editor | File exchange integration |
| Convert Office files in Node.js | Office file import and export |
| Add self-hosted realtime collaboration | Collaboration SDK overview |
| Let AI Agents read and edit Office content | AI SDK overview |
| Understand the CLI headless Runtime | Runtime reuse and daemon |
| Isolate AI Agent changes for human review | Worktree |
If you are unsure which path to choose, start with Get started.
How is this guide?