Skip to content

engine-core.md

Latest commit

 

History

History
113 lines (89 loc) · 4.18 KB

engine-core.md

File metadata and controls

113 lines (89 loc) · 4.18 KB

Draftly: Engine Core Architecture and System Design

The Decoupled Graphics Architecture

Draftly is built on a decoupled graphics architecture. Unlike traditional web-based design tools that rely on JavaScript for geometry calculations, Draftly offloads all high-computation tasks to a standalone system core written in Rust.

System Overview

graph TD
    subgraph "Frontend (React 19 + Vite)"
        UI[UI Shell & Panels]
        State[React State - Tool Selection]
        Canvas[Canvas Component]
    end

    subgraph "Bridge (WASM Glue)"
        Events[Mouse/Keyboard Events]
        Glue[wasm-bindgen / Glue Code]
    end

    subgraph "Graphics Engine (Rust Store)"
        Engine[DraftlyEngine Struct]
        Shapes[Scene Graph / Shapes List]
        Render[Draw Logic]
    end

    UI --> Events
    Events --> Glue
    Glue --> Engine
    Engine --> Shapes
    Shapes --> Render
    Render --> Canvas
Loading

Technical Stack

1. Rust and WebAssembly (WASM)

  • The Intelligence: All geometry math, shape storage, and rendering logic are implemented in Rust.
  • Precision: Near-native execution speed and the absence of Garbage Collection (GC) pauses during complex rendering tasks ensure high performance and reliability.

2. wasm-pack

  • The Translator: wasm-pack serves as the build tool that compiles Rust source code into a WebAssembly binary and generates the corresponding JavaScript glue code.
  • Bridge Logic: It produces a suite consisting of .js and .d.ts files, enabling the Rust module to be integrated as a standard ES module.

3. Bun Runtime

  • The Speed: The project is managed as a monorepo via Bun Workspaces. Bun handles package management and provides a high-performance development server for the API.

Development Workflow and Integration

When modifications are made to the Rust engine, the following pipeline is executed to synchronize the client application:

1. Rebuild the Engine

cd engine
wasm-pack build --target web

This command updates the engine/pkg directory with the latest binary and JavaScript interfaces.

2. Linking to Client

The client application connects to the engine via a symbolic link within the Bun monorepo:

# In client/package.json
"devDependencies": {
  "engine": "link:../engine/pkg"
}

Note: Due to Vite's dependency pre-bundling, a restart of the development server is required after significant changes to the WebAssembly structure:

bun run dev:client

Technical Deep Dive: The WASM Bridge

The connection between React and Rust utilizes a shared memory architecture rather than simple data passing.

Interaction Sequence

sequenceDiagram
    participant User
    participant React
    participant WASM_Glue
    participant Rust_Engine
    participant Canvas_API

    User->>React: Click on Canvas
    React->>WASM_Glue: engine.on_click(x, y, tool)
    WASM_Glue->>Rust_Engine: Update Internal Shape Vector
    Note over Rust_Engine: Logic: push Shape { x, y, type }
    loop Every Animation Frame
        React->>WASM_Glue: engine.render(ctx, w, h)
        WASM_Glue->>Rust_Engine: Access Canvas 2D Context
        Rust_Engine->>Canvas_API: ctx.fill_rect() / ctx.arc()
    end
Loading

Design Rationale

  1. Memory Isolation: The engine maintains a dedicated memory heap. The JavaScript layer transmits only primitive event data (coordinates, strings), mitigating the overhead of expensive data serialization and copying.
  2. Type Safety: The engine.d.ts file generated by wasm-pack ensures the React application has precise knowledge of the methods available in the Rust engine, facilitating full IDE support.
  3. Hardware Acceleration: By driving the CanvasRenderingContext2d directly from Rust, the system bypasses the overhead associated with JavaScript array iterations and complex object lookups.

Quality Assurance

Strict quality control is maintained across the entire development stack:

  • Root Level: bun run check (Parallelized Linting and Type Checking)
  • Rust Engine: cargo clippy (Production-grade linting following strict safety standards)
  • TypeScript/JavaScript: biome check (Modern, high-performance linter and formatter)