Architecture

Graphite Architecture

🚧 Note: More architecture documentation, UI improvements, and 3D support are planned! See Roadmap.md for details.

Overview

Graphite is structured around two main layers: the App layer and the Script layer.
The engine also provides a sandbox mode that protects the application from script errors.
This design creates an extensible environment in which user scripts can safely run, draw, and modify plot data without risking corruption of the main application state.

---

1. App Layer

The App layer manages the core application logic and runtime environment:

• Creating and loading the sandboxed script DLL
• Managing the main application window and rendering context
• Executing command-line flags passed at startup
• Handling the sandbox execution mechanism

Sandboxing Workflow (not fully implemented yet)

Graphite isolates script execution to prevent unsafe modifications:

1. Current state is first runs on fork isolated and independently from the main process.
2. If the script finishes successfully:
   • The main program runs operation.
3. If a failure occurs:
   • We don't run on main thread.
   • The user receives an error report.

This mechanism ensures that faulty or unstable scripts cannot crash Graphite but it is much slower because of twice execution.

---

2. Script Layer

Scripts are C++ classes that extend the ScriptInterface and are installed via the Graphite installer or CMake.

Script Lifecycle

Each script must implement the following methods:

• Init() – Called once when the script starts.
• Update(window_data) – Executed every frame and receives window state information.
• Draw() – Returns a vector of plots to be rendered by the App layer.
• Destroy() – Called once before the script shuts down.

Scripts have access to:

• Built-in tools such as the Script Interface and math modules
• Installed Graphite packages
• Local headers and resources

This gives developers the ability to write real-time, fully independent C++ scripts with complete control over logic and rendering.

---

3. Package System (planned)

Graphite packages follow the naming pattern: graphite-xyz

Packages are GitHub repositories and can be:

• Verified – Trusted, reviewed, and stable
• Unverified – Community-created; use at your own risk

Local Verification

Verification status is stored locally on the user’s machine:

• Faster access
• Increased security
• No reliance on network availability

Installation Structure

A package includes:

• Header files copied to gp_packages/
• A registration entry in gp_packages.txt containing:
  • Package name
  • Repository URL
  • Version

This structure enables fast installation, reliable versioning, and community-driven extensibility.

---

Future Improvements

Planned enhancements include:

• Additional Physics-Style Update Model
  A more advanced timestep model for simulations.

• ImGui Docking
  A docking-based UI layout for a more flexible editor workspace.

• In-Window Script Editor
  Editing and managing scripts directly within the Graphite interface.

• In-Window Logging Panel
  Integrated logging for both the App layer and user scripts.

---