Skip to content
alpha 0.1.0-alpha.7 is on crates.io. Install the CLI Start here

Architecture overview

Auro is an application shell around a renderer it does not own. Every architectural rule below follows from that split.

+-----------------------------------------------------------+
| auro-cli    new . dev . build . bundle . add . doctor     |
+-----------------------------------------------------------+
| auro-core                                                 |
|   App . WindowManager . Config . Lifecycle .              |
|   Command registry . State store . Event bus . Instance    |
+--------------+-------------------+------------------------+
| auro-ui      | auro-ipc          | auro-perms             |
| GPUI + kit   | typed bus         | capabilities           |
+--------------+-------------------+------------------------+
| auro-plugins   in-process (cdylib) | out-of-process RPC   |
+-----------------------------------------------------------+
| auro-bundle . auro-update . auro-sign                     |
+-----------------------------------------------------------+

The diagram is a layering, not a dependency graph: a layer may use the layer below it, and auro-core is the only crate that composes the others. The Phase 0 workspace fixes the current Cargo.toml edges for the materialized crates; the full crate graph remains the intended direction as later phases land.

Responsibilities

LayerOwnsMust not
auro-cliproject scaffolding, dev loop, bundling entry points, diagnosticscontain runtime logic the app needs
auro-coreApp, window manager, config, lifecycle, command registry, state store, event bus, single-instance guard and forwardingrender anything
auro-uiGPUI re-export, toolkit seam, tokens, minimal primitivesship a component toolkit; check permissions
auro-ipctyped command transport, schema derivation, event deliverydecide policy
auro-permscapability manifests, runtime enforcement for plugin and content boundariesguard code that the compiler already guards
auro-pluginsplugin manifests, in-process cdylib hosts, out-of-process RPCassume plugin code is trusted
auro-servicesplatform services: autostart, notifications, keychain, global shortcuts, tray, deep links (specs 0017-0022)perform OS work the app did not ask for
auro-bundle, auro-update, auro-signpackaging per platform, signed manifests, staged downloads, platform apply/rollback and notarization tooling, key handlingrun inside the app's main loop

Data flow of one interaction

  1. Main thread. GPUI owns it. A user event arrives and a view handler runs.
  2. Dispatch. The handler either mutates state directly (cheap, synchronous) or asks the command registry for an async command.
  3. Off-thread work. The command is a plain async fn on the tokio runtime. File I/O, network, parsing - anything that can block - happens here.
  4. Return. The command returns a typed Result<T, AuroError>. There is no serialization boundary unless the command crosses the plugin boundary.
  5. Back to the main thread. The result is applied by updating an Entity and calling cx.notify(), which schedules a render.
// Current workspace API (unpublished).
#[auro::command]
async fn save_document(path: PathBuf, body: String) -> Result<Saved, AuroError> {
    tokio::fs::write(&path, body).await?;
    Ok(Saved { path, bytes: body.len() })
}

The call site is a Rust call, so a wrong argument type is a compile error rather than an invoke failure at runtime.

Where state lives

  • UI state lives in GPUI entities on the main thread.
  • Application state lives in the core state store, reachable from commands.
  • Reloadable state is captured as a host-owned serde snapshot so a hot reload or a state-preserving restart can restore opted-in state. Opt-in hot mode patches a small boundary crate in-process; the contract is in spec 0004, the mechanism in ADR 0008 and the boundary layout in ADR 0022.

The boundary rule that keeps this honest: nothing outside auro-core holds a global mutable reference to app state, and nothing on the main thread blocks on I/O.

What is not decided yet

Tracked in ROADMAP §8:

  • a scripting layer for plugin UIs, or Rust only;
  • out-of-process plugins first, or in-process first.

Resolved: component kit — Auro ships no toolkit; the application chooses one (ADR 0009, choosing a toolkit).

Anything in this book that depends on those answers is marked as open where it appears.