How Spark works
Spark is a Tauri 2 desktop app: a React renderer, a Rust backend and a local MCP bridge. This page is the map. The other pages zoom into one part at a time.
Three objects, three jobs
- The workspace is the document: tabs, tiles, one layout per tab per mode, the active tab, the theme. It is the single truth for what the window shows, and the only thing that gets persisted.
- The registry is what the code can do right now: tile types, actions, commands, services and events contributed by the extensions that are active. It is rebuilt when an extension is activated, removed or imported.
- The extension manager decides which extensions are installed and enabled. Installed packages live outside the repository, in the app configuration directory.
Layers
| Layer | Path | Job |
|---|---|---|
| Contracts | src/sdk | Manifest, SparkAPI, tile definitions, actions, services, events, React contract. |
| Domain | src/core | Workspace, journal, brief, contribution registry, extension lifecycle, persistence, settings. |
| Application | src/app | Startup, discovery, package loading, marketplace, MCP bridge, global theme. |
| Interface | src/ui | Window, tabs, dockview, rail, Store, splash, error boundaries. |
| Extensions | src/extensions | Built-in extensions: manifest, React module, styles, cooperation APIs, media. |
| Native | src-tauri | Disk storage, imported packages, files, PTY, PDF, MCP, agent configuration. |
| Shared | src/shared | Design system, brand, agent list, utilities. |
Startup
main.tsx
└─ createRuntime()
├─ workspace_load / settings_load
├─ new TileViews()
├─ discoverExtensions(views)
│ ├─ built-in manifests and modules (import.meta.glob)
│ └─ extension_list → imported packages
├─ seedCoreExtensions()
├─ Workspace + persistence
├─ Registry
├─ ExtensionManager.restore()
├─ Marketplace.restore() (background)
└─ attachMcp()
└─ SparkShellThe splash stays visible for at least 1.2 seconds. The MCP bridge is attached before the main window renders, so an agent never sees a half-built workspace.
Data flow
Interface ──► Runtime ──► Workspace / Registry / ExtensionManager
│ │
│ ├─ contributions (tiles, actions, commands)
│ └─ per-extension state
▼
invoke Tauri ──► Rust ──► files, sockets, PTY, network
▲
MCP agent ──► attachMcp ──► Runtime ──► same primitives, source "agent"The interface and the agents go through the same primitives. Only the journal source changes:human, agent or system.
Invariants
- A terminal session dies when its tile is unmounted. The Store is therefore an overlay, never a replacement for the workspace.
- A tab opened by an agent appears in the background and never takes focus.
- Tiles keep their id and their data when an extension is disabled; only their view becomes unavailable.
- An action result, a surface and a brief are bounded. Heavy content stays in the tile.
- An imported extension runs with the window's privileges. See the trust model.
Next
Build and run to get a window on screen, thenWorkspace and MCP bridge for the two halves an extension or an agent touches.