# zackradisic/tyvm architecture

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

- Interactive diagram: https://gitdiagram.com/zackradisic/tyvm
- Repository: https://github.com/zackradisic/tyvm

## Overview

##### What this project is (type + purpose)

**tyvm is a “compiler + bytecode VM” system for type-level TypeScript**:

- **Compiler (Rust)**: takes *TypeScript type-level source* → parses to AST (via **oxc**) → lowers to a custom **IR** → emits **tyvm bytecode**.
- **VM (Zig)**: a **stack-based interpreter** that executes the bytecode.
- **Web demo/site (Next.js)**: a separate `site/` app that loads a **WASM build** of the VM (and/or related artifacts) to run in the browser.

##### Read the repo structure as architecture boundaries

Top-level folders clearly map to major components:

##### Compiler (Rust)
- `Cargo.toml`, `src/`
- Key files:
- `src/main.rs` (likely CLI entry)
- `src/lib.rs` (library API)
- `src/compile.rs` (compilation pipeline)
- `src/ir.rs` (IR definitions)
- `src/ir_transform.rs`, `src/ir_transform_oxc.rs` (AST→IR + IR passes)
- `src/op.rs` (bytecode ops / instruction set)
- `src/common.rs` (shared types/util)

##### VM (Zig)
- `vm/` with many runtime pieces:
- `vm/main.zig` (native entry)
- `vm/main_wasm.zig` (WASM entry)
- `vm/vm.zig`, `vm/tyvm.zig` (core VM)
- `vm/compiler.zig` (potentially bytecode loader/assembler or compilation-related utilities on Zig side)
- `vm/json.zig` (I/O / decoding support)
- `vm/raf/*` (requestAnimationFrame integration for WASM/browser scheduling)
- Build tooling:
- `build.zig` (Zig build, including wasm output)

##### Web site / demo
- `site/` is a Next.js app:
- `site/src/pages/*` (pages like `index.tsx`, `mnist2.tsx`)
- `site/src/lib/load_wasm.ts`, `site/src/lib/wasm_types.ts` (WASM bridge)
- `site/public/tyvm.wasm` (prebuilt wasm artifact checked in)
- `site/public/*.ts` (examples / demos: `mnist.ts`, `flap.ts`, `std.ts`)

##### Cross-language integration points
- `include/tyvm_compiler.h`: indicates a **C header** for exposing the compiler as a C ABI (used by Zig or other hosts).
- Build/devenv:
- `Makefile`, `flake.nix`, `shell.nix` etc.

##### Type-level TS Source
- Inputs: `test/*.ts`, `site/public/*.ts` (examples)
##### IR Layer (tyvm IR)
- Nodes: “AST→IR lowering” (`ir_transform_oxc.rs`)
- “IR transforms / passes” (`ir_transform.rs`)
##### Bytecode Emitter
- “IR → bytecode” (`compile.rs`, `op.rs`)
- Output artifact: “tyvm bytecode”
##### VM Runtime (Zig)
- “Bytecode loader/decoder”
- “Stack machine executor”
##### Outputs
- “Evaluated type-level result / value model”
- Or “converted schema” (future use-case from README: GraphQL/Prisma/JSON Schema)

- “TS types” → “AST” → “IR” → “Bytecode” → “Execution result”

**Native CLI path**
- User runs: `tyvm` (Rust `src/main.rs`)
- Compiler produces bytecode (in-memory or file)
- VM runs:
- either as separate executable (`vm/main.zig`) consuming bytecode
- or embedded via FFI (Rust exports C ABI via `include/tyvm_compiler.h`, Zig calls it), depending on actual integration

**Browser path**
- Next.js `site/` serves UI
- UI loads `public/tyvm.wasm`
- JS/TS glue (`load_wasm.ts`, `wasm_types.ts`) calls into WASM exports (from `vm/main_wasm.zig`)
- WASM executes bytecode; results returned to UI

This view should make it obvious there are **two runtime environments**:
- Native (Zig executable)
- Browser (WASM module)

##### An “interfaces/contracts” callout (third mini-view)

Because this project is “compiler + VM”, the most important architecture contract is the **bytecode format + instruction set**:

- Both compiler and VM depend on this contract.
- “Instruction enum / opcode table” (Rust)
- “Opcode dispatch / interpreter loop” (Zig)

**FFI boundary**:
- “C ABI: tyvm_compiler.h”
- Who consumes it (likely Zig or other host)

When you label components, add small “implemented in” notes:

- Parser: “oxc” (external)
- Lowering: `src/ir_transform_oxc.rs`
- IR: `src/ir.rs`
- IR passes: `src/ir_transform.rs`
- Bytecode emit / compile driver: `src/compile.rs`
- Opcodes: `src/op.rs`
- CLI/library: `src/main.rs`, `src/lib.rs`

- VM core: `vm/vm.zig`, `vm/tyvm.zig`
- Entrypoints:
- native: `vm/main.zig`
- wasm: `vm/main_wasm.zig`
- Browser scheduling: `vm/raf/raf_wasm.zig`
- Utilities: `vm/json.zig`

##### Web UI
- Next pages: `site/src/pages/*`
- WASM loader/types: `site/src/lib/load_wasm.ts`, `site/src/lib/wasm_types.ts`
- Artifact: `site/public/tyvm.wasm`

##### Next.js UI → WASM VM
- “instantiate wasm” + “call exports”
##### Compiler → Bytecode
- output type: “bytecode buffer / file”
##### VM ← Bytecode
- “decode + execute”
##### (Optional) Compiler ↔ VM contract
- both share “bytecode spec” (even if not in a single file)
##### Zig WASM build → site/public/tyvm.wasm
- artifact flow (build pipeline)

##### Architectural patterns to highlight (specific to tyvm)

- **Multi-stage compilation pipeline**: AST → IR → bytecode
- “AST Adapter Layer” feeding the same IR
- **Stable VM contract**: stack machine interpreter over a defined opcode set
- **Multi-target runtime**: native + wasm
- **Functional-language runtime optimizations** (called out in README):
- structural sharing (HAMT/RRB)
- static RC optimization / reuse (Perceus-inspired)

- TS type-level source (tests/examples)
→ oxc parser (AST)
→ IR builder (tyvm IR)
→ IR transforms
→ bytecode emitter (opcodes)
→ bytecode
→ Zig VM (native/wasm)
→ result

- Native:
- `tyvm` compiler CLI → bytecode → `tyvm` VM native exe
- Web:
- Next.js pages → load wasm → execute bytecode in wasm VM → render result

- Bytecode format / opcode set shared between Rust compiler and Zig VM
- C ABI boundary via `include/tyvm_compiler.h` (if used)

- “oxc parser” called out as external dependency
- “IR (custom)” called out as the decoupling layer
- “Bytecode ISA / opcodes” as the key shared contract
- “Stack-based VM” explicitly stated
- “Native vs WASM entrypoints” (`main.zig` vs `main_wasm.zig`)
- “Next.js demo” and “WASM loader glue”
- Distinguish “build-time artifact” (wasm) from “runtime data” (bytecode)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram 1: Toolchain Pipeline (Compile + Execute)
%% =========================
subgraph "1) Compilation + Execution Pipeline (Toolchain)"
direction TB

subgraph "Inputs (Type-level TypeScript)"
direction TB
TS_TESTS["Type-level TS test inputs\n(test/*.ts)"]:::ts
TS_MNIST_PROGS["MNIST type-level programs\n(test/mnist/*.ts)"]:::ts
TS_WEB_EXAMPLES["Browser example programs\n(site/public/*.ts)"]:::ts
end

subgraph "Compiler (Rust)"
direction TB
R_CLI["Compiler CLI\n(tyvm)"]:::rust
R_LIB["Compiler library API"]:::rust
R_COMMON["Shared types/utilities"]:::rust

OXC["oxc TypeScript parser\n(external)"]:::external
AST_DOC["AST"]:::artifact

R_LOWER["AST → IR lowering\n(oxc adapter)"]:::rust
IR_DOC["tyvm IR\n(custom)"]:::artifact
R_PASSES["IR transforms / passes"]:::rust
R_EMIT["IR → Bytecode emitter\n(compile driver)"]:::rust

ISA["Bytecode ISA / opcode set\n(shared contract)"]:::contract
BYTECODE_DOC["tyvm bytecode"]:::artifact
end

subgraph "VM Runtime (Zig)"
direction TB
Z_LOADER["Bytecode loader / decoder"]:::zig
Z_VM["Stack-based interpreter\n(execution loop)"]:::zig
Z_RT["Runtime data structures + memory mgmt\n(structural sharing, RC reuse)"]:::note
RESULT_DOC["Execution result\n(evaluated type-level model)"]:::artifact
end

%% Flow
TS_TESTS -->|"TS_types"| OXC
TS_MNIST_PROGS -->|"TS_types"| OXC
TS_WEB_EXAMPLES -->|"TS_types"| OXC

OXC -->|"parse"| AST_DOC
AST_DOC -->|"lower"| R_LOWER
R_LOWER -->|"build"| IR_DOC
IR_DOC -->|"optimize"| R_PASSES
R_PASSES -->|"emit"| R_EMIT
R_EMIT -->|"encode"| BYTECODE_DOC

ISA -.->|"defines_opcodes"| R_EMIT
ISA -.->|"dispatch_table"| Z_VM

BYTECODE_DOC -->|"decode"| Z_LOADER
Z_LOADER -->|"execute"| Z_VM
Z_VM -->|"alloc/rc/share"| Z_RT
Z_VM -->|"return"| RESULT_DOC

%% Compiler entrypoints relationships (vertical, non-pipeline)
R_CLI -->|"uses"| R_LIB
R_LIB -->|"uses"| R_COMMON
R_LIB -->|"drives"| R_EMIT
end


%% =========================
%% Diagram 2: Deployment Targets (Native + Browser/WASM)
%% =========================
subgraph "2) Deployment Targets (Native + Browser/WASM)"
direction TB

subgraph "Native path"
direction TB
USER_NATIVE["User (native shell)"]:::external
R_CLI_NATIVE["Rust compiler CLI"]:::rust
BYTECODE_NATIVE["Bytecode buffer/file"]:::artifact

Z_NATIVE_ENTRY["Zig VM native entrypoint"]:::zig
Z_VM_NATIVE["Zig VM core"]:::zig
NATIVE_OUT["Native result/output"]:::artifact
end

subgraph "Browser path"
direction TB
BROWSER["Browser runtime"]:::external

NEXT_SITE["Next.js web demo (site/)"]:::web
NEXT_PAGES["UI pages\n(index / mnist demo)"]:::web
WASM_GLUE["WASM loader + bindings\n(TS glue)"]:::web

Z_BUILD["zig build\n(native + wasm)"]:::build
WASM_ART["tyvm.wasm"]:::artifact

Z_WASM_ENTRY["Zig VM WASM entrypoint"]:::zig
Z_VM_WASM["Zig VM core (WASM)"]:::zig
WEB_OUT["Result → UI render"]:::artifact

RAF_FACADE["RAF facade"]:::zig
RAF_WASM["requestAnimationFrame integration (WASM)"]:::zig
end

%% Native runtime flow
USER_NATIVE -->|"run"| R_CLI_NATIVE
R_CLI_NATIVE -->|"compile_to_bytecode"| BYTECODE_NATIVE
BYTECODE_NATIVE -->|"consume"| Z_NATIVE_ENTRY
Z_NATIVE_ENTRY -->|"calls"| Z_VM_NATIVE
Z_VM_NATIVE -->|"produce"| NATIVE_OUT

%% Browser runtime flow
BROWSER -->|"loads"| NEXT_SITE
NEXT_SITE -->|"routes"| NEXT_PAGES
NEXT_PAGES -->|"instantiate"| WASM_GLUE
Z_BUILD -.->|"produces"| WASM_ART
NEXT_SITE -->|"serves_static"| WASM_ART
WASM_GLUE -->|"calls_exports"| Z_WASM_ENTRY
Z_WASM_ENTRY -->|"runs"| Z_VM_WASM
Z_VM_WASM -->|"returns"| WEB_OUT
WEB_OUT -->|"render"| NEXT_PAGES

%% RAF wiring (WASM scheduling)
RAF_FACADE -->|"select_impl"| RAF_WASM
RAF_WASM -->|"schedule_ticks"| Z_VM_WASM
end


%% =========================
%% Diagram 3: Contracts + FFI boundaries
%% =========================
subgraph "3) Interfaces / Contracts"
direction TB

subgraph "Shared contract: Bytecode + Opcodes"
direction TB
ISA2["Bytecode format + opcode table\n(compiler ↔ VM contract)"]:::contract
R_OPS["Rust opcode definitions"]:::rust
Z_DISPATCH["Zig opcode dispatch/decoder"]:::zig
end

subgraph "FFI boundary (optional integration)"
direction TB
C_ABI["C ABI header\n(compiler integration)"]:::ffi
R_LIB_FFI["Rust compiler library (exported API)"]:::rust
Z_HOST["Zig host / other consumers"]:::zig
end

ISA2 -->|"implemented_as"| R_OPS
ISA2 -->|"implemented_as"| Z_DISPATCH

R_LIB_FFI -->|"exports"| C_ABI
Z_HOST -->|"includes"| C_ABI
end


%% =========================
%% Cross-diagram connections (kept minimal)
%% =========================
R_CLI_NATIVE -->|"same_as"| R_CLI
Z_VM_NATIVE -->|"same_core_as"| Z_VM
Z_VM_WASM -->|"same_core_as"| Z_VM
BYTECODE_NATIVE -->|"same_format"| BYTECODE_DOC
WASM_ART -.->|"built_from"| Z_WASM_ENTRY


%% =========================
%% Click events (from component mapping)
%% =========================
click R_CLI "https://github.com/zackradisic/tyvm/blob/master/src/main.rs"
click R_LIB "https://github.com/zackradisic/tyvm/blob/master/src/lib.rs"
click R_EMIT "https://github.com/zackradisic/tyvm/blob/master/src/compile.rs"
click R_COMMON "https://github.com/zackradisic/tyvm/blob/master/src/common.rs"
click IR_DOC "https://github.com/zackradisic/tyvm/blob/master/src/ir.rs"
click R_LOWER "https://github.com/zackradisic/tyvm/blob/master/src/ir_transform_oxc.rs"
click R_PASSES "https://github.com/zackradisic/tyvm/blob/master/src/ir_transform.rs"
click R_OPS "https://github.com/zackradisic/tyvm/blob/master/src/op.rs"

click Z_NATIVE_ENTRY "https://github.com/zackradisic/tyvm/blob/master/vm/main.zig"
click Z_WASM_ENTRY "https://github.com/zackradisic/tyvm/blob/master/vm/main_wasm.zig"
click Z_VM "https://github.com/zackradisic/tyvm/blob/master/vm/vm.zig"
click Z_VM_NATIVE "https://github.com/zackradisic/tyvm/blob/master/vm/vm.zig"
click Z_VM_WASM "https://github.com/zackradisic/tyvm/blob/master/vm/vm.zig"
click Z_HOST "https://github.com/zackradisic/tyvm/blob/master/vm/tyvm.zig"
click Z_LOADER "https://github.com/zackradisic/tyvm/blob/master/vm/compiler.zig"
click Z_DISPATCH "https://github.com/zackradisic/tyvm/blob/master/vm/compiler.zig"
click Z_RT "https://github.com/zackradisic/tyvm/blob/master/vm/json.zig"

click RAF_WASM "https://github.com/zackradisic/tyvm/blob/master/vm/raf/raf_wasm.zig"
click RAF_FACADE "https://github.com/zackradisic/tyvm/blob/master/vm/raf.zig"
click Z_BUILD "https://github.com/zackradisic/tyvm/blob/master/build.zig"

click NEXT_SITE "https://github.com/zackradisic/tyvm/tree/master/site/"
click NEXT_PAGES "https://github.com/zackradisic/tyvm/blob/master/site/src/pages/index.tsx"
click NEXT_PAGES "https://github.com/zackradisic/tyvm/blob/master/site/src/pages/mnist2.tsx"
click NEXT_SITE "https://github.com/zackradisic/tyvm/blob/master/site/src/pages/_app.tsx"
click NEXT_SITE "https://github.com/zackradisic/tyvm/blob/master/site/src/pages/_document.tsx"
click WASM_GLUE "https://github.com/zackradisic/tyvm/blob/master/site/src/lib/load_wasm.ts"
click WASM_GLUE "https://github.com/zackradisic/tyvm/blob/master/site/src/lib/wasm_types.ts"
click WASM_ART "https://github.com/zackradisic/tyvm/blob/master/site/public/tyvm.wasm"
click TS_WEB_EXAMPLES "https://github.com/zackradisic/tyvm/blob/master/site/public/std.ts"
click TS_WEB_EXAMPLES "https://github.com/zackradisic/tyvm/blob/master/site/public/flap.ts"
click TS_WEB_EXAMPLES "https://github.com/zackradisic/tyvm/blob/master/site/public/mnist.ts"

click TS_TESTS "https://github.com/zackradisic/tyvm/tree/master/test/"
click TS_MNIST_PROGS "https://github.com/zackradisic/tyvm/blob/master/test/mnist/general.ts"
click TS_MNIST_PROGS "https://github.com/zackradisic/tyvm/blob/master/test/mnist/norm.ts"
click RESULT_DOC "https://github.com/zackradisic/tyvm/tree/master/test/mnist/data/"

click C_ABI "https://github.com/zackradisic/tyvm/blob/master/include/tyvm_compiler.h"


%% =========================
%% Styles (color is required)
%% =========================
classDef rust fill:#D44A2D,stroke:#7A1F12,stroke-width:1.5px,color:#ffffff;
classDef zig fill:#F3C623,stroke:#8A6A00,stroke-width:1.5px,color:#1a1a1a;
classDef web fill:#3B82F6,stroke:#1E3A8A,stroke-width:1.5px,color:#ffffff;
classDef ts fill:#22C55E,stroke:#166534,stroke-width:1.5px,color:#ffffff;
classDef external fill:#9CA3AF,stroke:#374151,stroke-width:1.5px,color:#111827;
classDef artifact fill:#FFFFFF,stroke:#111827,stroke-width:1.5px,color:#111827;
classDef contract fill:#A855F7,stroke:#5B21B6,stroke-width:1.5px,color:#ffffff;
classDef ffi fill:#14B8A6,stroke:#0F766E,stroke-width:1.5px,color:#ffffff;
classDef build fill:#F97316,stroke:#9A3412,stroke-width:1.5px,color:#ffffff;
classDef note fill:#FEF3C7,stroke:#B45309,stroke-width:1.5px,color:#7C2D12;

class TS_TESTS,TS_MNIST_PROGS,TS_WEB_EXAMPLES ts
class OXC,USER_NATIVE,BROWSER external
class AST_DOC,IR_DOC,BYTECODE_DOC,RESULT_DOC,BYTECODE_NATIVE,WASM_ART,NATIVE_OUT,WEB_OUT artifact
class ISA,ISA2 contract
class C_ABI ffi
class Z_BUILD build
class Z_RT note
```
