# hyperlight-dev/hyperlight-wasm architecture

> Architecture diagram of the GitHub repository hyperlight-dev/hyperlight-wasm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hyperlight-dev/hyperlight-wasm
- Repository: https://github.com/hyperlight-dev/hyperlight-wasm

## Overview

##### Project type and purpose
- This is a system‐level Rust library plus tools (“Hyperlight‑Wasm”) whose goal is to execute untrusted WebAssembly modules inside a lightweight VM‑backed sandbox. It provides:
- A core library crate (`hyperlight_wasm`) exposing APIs to create/run sandboxes
- An ahead‑of‑time compiler binary (`hyperlight_wasm_aot`)
- A macro crate (`hyperlight_wasm_macro`) for component‑model codegen
- A sample host runtime (`wasm_runtime`) and example modules
- Build scripts and helpers under `Justfile` and shell/PowerShell scripts

##### File structure
- Top‑level crates:
- src/hyperlight_wasm (core library)
- src/hyperlight_wasm_aot (AOT compiler)
- src/hyperlight_wasm_macro (macro & host‑bindgen)
- src/wasm_runtime (host application binary)
- src/examples_common, src/rust_wasm_samples, src/wasmsamples (example modules & helper code)
- Build & CI: `.devcontainer/`, `.github/workflows/`, `Justfile`, scripts under each crate
- Config & tooling: Cargo.toml, rust-toolchain.toml, rustfmt.toml

##### Key architectural patterns
- **Layered crates**: Host application → API library → sandbox internals → hypervisor interface
- **Builder pattern**: `SandboxBuilder` constructs VMs, loads modules, wires host functions
- **Optional AOT**: transforms Wasm to native code before sandbox load
- **Macro integration**: codegen for component‑model interfaces at compile time

##### Main components
a. Host Application Layer
- `wasm_runtime` binary or customer host app using `hyperlight_wasm` APIs
- Example binaries (`helloworld`, `hostfuncs`, `metrics`)
b. Library/API Layer
- `hyperlight_wasm` public modules (`build_info`, `lib.rs`)
- `SandboxBuilder` → config, metrics, hostfunc bindings
c. AOT Compiler
- `hyperlight_wasm_aot` converts `.wasm` → native
d. Macro Codegen
- `hyperlight_wasm_macro` → generates host‑side bindings for component model
e. Sandbox Runtime Internals
- Modules under `src/sandbox/`: `loaded_wasm_sandbox`, `wasm_sandbox`, `metrics`, `proto_wasm_sandbox`
f. Hypervisor Interfaces
- Platform abstraction layers: KVM (Linux), WHP (Windows), MSHV
- Underlying OS driver (/dev/kvm, HYPERVISOR_PLATFORM)
g. Guest Wasm Modules
- Prebuilt examples (`.c`, Rust, component model .wit)
h. Build & CI Tools (side notes)
- `just build`, scripts, GitHub Actions

##### Relationships & data flows
- At build time:
- Host code + macros → Rust compiler → host binary + generated bindings
- AOT compiler processes Wasm modules (optional)
- At runtime:
1. Host app calls `SandboxBuilder::new()` → config
2. Builder uses hypervisor interface to spin up VM
3. Wasm module bytes (or AOT image) loaded into sandbox process
4. Execution inside VM‑backed sandbox
5. Host ↔ guest communication via hostfunc bridges or component model
6. Metrics/events surfaced back through API
- CI and devcontainer are orthogonal but support reproducible builds/tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "1. Host Application & CLI"
        wasm_runtime["wasm_runtime\n(binary)"]:::crate
        hello["helloworld\n(example)"]:::example
        hostfuncsEx["hostfuncs\n(example)"]:::example
        metricsEx["metrics\n(example)"]:::example
        rustWasmEx["rust_wasm_examples\n(example)"]:::example
    end

    subgraph "2. API & Macros"
        crateAPI["hyperlight_wasm\n(core library)"]:::crate
        sandboxBuilder["SandboxBuilder"]:::component
        macroCrate["hyperlight_wasm_macro\n(macro codegen)"]:::crate
    end

    subgraph "3. AOT Compiler"
        aot["hyperlight_wasm_aot\n(AOT compiler)"]:::crate
    end

    subgraph "4. Sandbox Internals"
        wasmSandbox["wasm_sandbox"]:::component
        loadedSandbox["loaded_wasm_sandbox"]:::component
        metricsMod["metrics"]:::component
        protoSandbox["proto_wasm_sandbox"]:::component
    end

    subgraph "5. Hypervisor Interface"
        hypervisor["Hypervisor Backends\n(KVM / WHP / MSHV)"]:::external
    end

    subgraph "6. OS/Hardware"
        os["OS Kernel / /dev/kvm\nHYPERVISOR_PLATFORM"]:::external
    end

    %% Build-time flows
    hello -->|"builds with"| crateAPI
    hostfuncsEx -->|"builds with"| crateAPI
    metricsEx -->|"builds with"| crateAPI
    rustWasmEx -->|"builds with"| crateAPI
    crateAPI -->|"uses macro"| macroCrate
    crateAPI -->|"optionally uses"| aot

    %% Runtime flows
    wasm_runtime -->|"calls API"| crateAPI
    crateAPI -->|"SandboxBuilder::new()"| sandboxBuilder
    sandboxBuilder -->|"constructs"| wasmSandbox
    sandboxBuilder -->|"constructs"| loadedSandbox
    sandboxBuilder -->|"initializes"| metricsMod
    sandboxBuilder -->|"initializes"| protoSandbox
    wasmSandbox -->|"runs on"| hypervisor
    loadedSandbox -->|"runs on"| hypervisor
    protoSandbox -->|"bridges to"| hypervisor
    hypervisor -->|"interfaces with"| os

    %% Click Events
    click wasm_runtime "https://github.com/hyperlight-dev/hyperlight-wasm/blob/main/src/wasm_runtime/src/main.rs"
    click hello "https://github.com/hyperlight-dev/hyperlight-wasm/blob/main/src/hyperlight_wasm/examples/helloworld/main.rs"
    click hostfuncsEx "https://github.com/hyperlight-dev/hyperlight-wasm/blob/main/src/hyperlight_wasm/examples/hostfuncs/main.rs"
    click metricsEx "https://github.com/hyperlight-dev/hyperlight-wasm/blob/main/src/hyperlight_wasm/examples/metrics/main.rs"
    click rustWasmEx "https://github.com/hyperlight-dev/hyperlight-wasm/blob/main/src/hyperlight_wasm/examples/rust_wasm_examples/main.rs"
    click crateAPI "https://github.com/hyperlight-dev/hyperlight-wasm/blob/main/src/hyperlight_wasm/src/lib.rs"
    click sandboxBuilder "https://github.com/hyperlight-dev/hyperlight-wasm/blob/main/src/hyperlight_wasm/src/sandbox/sandbox_builder.rs"
    click wasmSandbox "https://github.com/hyperlight-dev/hyperlight-wasm/blob/main/src/hyperlight_wasm/src/sandbox/wasm_sandbox.rs"
    click loadedSandbox "https://github.com/hyperlight-dev/hyperlight-wasm/blob/main/src/hyperlight_wasm/src/sandbox/loaded_wasm_sandbox.rs"
    click metricsMod "https://github.com/hyperlight-dev/hyperlight-wasm/blob/main/src/hyperlight_wasm/src/sandbox/metrics.rs"
    click protoSandbox "https://github.com/hyperlight-dev/hyperlight-wasm/blob/main/src/hyperlight_wasm/src/sandbox/proto_wasm_sandbox.rs"
    click aot "https://github.com/hyperlight-dev/hyperlight-wasm/blob/main/src/hyperlight_wasm_aot/src/main.rs"
    click macroCrate "https://github.com/hyperlight-dev/hyperlight-wasm/blob/main/src/hyperlight_wasm_macro/src/lib.rs"

    %% Styling
    classDef crate fill:#AED6F1,stroke:#3498DB,stroke-width:2px;
    classDef component fill:#ABEBC6,stroke:#27AE60,stroke-width:2px;
    classDef example fill:#D6EAF8,stroke:#5DADE2,stroke-width:2px;
    classDef external fill:#F2F3F4,stroke:#B3B6B7,stroke-width:2px;
```
