Architecture Overview

This platform uses a modular architecture designed to separate core engine concerns from high-level user workflows. This ensures stability and performance while providing flexibility for developing specialized tools.

Building Blocks

The SDK is organized into layers, each serving a specific role in the application lifecycle.

1. Core Engine

The foundation of the client is built on a modular system of Bevy Plugins, allowing you to enable, disable, or swap engine-level functionality. Custom low-level plugins can be added to extend core capabilities.

Example: Integrate with a hardware accessory, software package, or REST API to provide an implementation for higher-level tools.

2. Runtime

The Runtime is the authoritative entry point for all application commands. This asynchronous engine coordinates statement execution, manages versioned state, and handles the lifecycle of tools and background tasks.

Because the Runtime is decoupled from the user interface, it can be driven by multiple frontends:

Desktop & Web UI: Standard user interactions.
Automation Scripts: Headless execution of workflows.
Integration APIs: Remote commands from external services.
CLI: Direct command-line interaction for developers.

Example: Connecting an LLM-based agent to the Runtime via a network port to perform operations alongside the user.

3. Objects & Statements

The system uses a versioned state architecture. Persistent project data is defined as Objects, which are automatically versioned and synchronized. To modify these objects, use Statements.

Example: Defining an object to store Comments and an UpdateComment mutation, which versions the change when applied.

4. Tools

Tools combine 3D scene interactions and UI form inputs into a unified asynchronous task system. They process user intent to produce statements. A tool can group multiple statements into an atomic transaction, ensuring that complex operations can be undone or redone in a single step.

Example: Creating a PointPlacementTool that waits for a 3D viewport click before emitting a statement to spawn an object.

5. Routes & UI

The top layer consists of Routes and UI, including Editor Pages. This is where multiple tools are composed into a cohesive workspace.

Example: Building a GeologyEditor page that groups a measurement tool, a cross-section tool, and a custom sidebar for stratigraphic data.

Scalability and Depth

You will likely spend most of your time in the high-level layers, using Tools and Editors to compose existing functionality. As needs grow, you can create custom Objects or modify Bevy rendering logic, maintaining the safety and synchronization provided by the core SDK.

Extensibility Paths

There are two ways to extend the platform:

Compiled Plugins: Deep, compile-time integration with access to the Rust source code and the Bevy engine.
Runtime Extensions: Sandboxed WASM scripts for third-party automation and lightweight tool development without recompiling the client.

Object Model