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

LayerPathJob
Contractssrc/sdkManifest, SparkAPI, tile definitions, actions, services, events, React contract.
Domainsrc/coreWorkspace, journal, brief, contribution registry, extension lifecycle, persistence, settings.
Applicationsrc/appStartup, discovery, package loading, marketplace, MCP bridge, global theme.
Interfacesrc/uiWindow, tabs, dockview, rail, Store, splash, error boundaries.
Extensionssrc/extensionsBuilt-in extensions: manifest, React module, styles, cooperation APIs, media.
Nativesrc-tauriDisk storage, imported packages, files, PTY, PDF, MCP, agent configuration.
Sharedsrc/sharedDesign 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()
  └─ SparkShell

The 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.