# vbxq/elyra architecture

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

- Interactive diagram: https://gitdiagram.com/vbxq/elyra
- Repository: https://github.com/vbxq/elyra

## Overview

Elyra is a standalone language implementation centered on a register-based bytecode VM, with generational garbage collection, isolated heaps and a tiered Cranelift JIT. The principal workflow is source input through the CLI or public API, staged compilation, and VM execution; the repository also provides assembly, REPL, module loading, standard-library and native-module capabilities. The pipeline source confirms staged execution and caching; other links reflect the repository layout and README, not inspection of unsampled implementations.

Main entry points: [`driver/src/pipeline/pipeline.rs`](https://github.com/vbxq/elyra/blob/master/driver/src/pipeline/pipeline.rs) (Compile pipeline), [`runtime/src/vm/core.rs`](https://github.com/vbxq/elyra/blob/master/runtime/src/vm/core.rs) (Register VM), [`driver/src/api/mod.rs`](https://github.com/vbxq/elyra/blob/master/driver/src/api/mod.rs) (Driver API), [`driver/src/modules/loader/mod.rs`](https://github.com/vbxq/elyra/blob/master/driver/src/modules/loader/mod.rs) (Module loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_cli["CLI commands<br/>[run.rs]"]
  node_public_api["Public API<br/>[mod.rs]"]
  node_repl["REPL<br/>[repl.rs]"]
  node_driver["Driver API<br/>[mod.rs]"]
end

subgraph group_compile["Compilation"]
  node_pipeline["Compile pipeline<br/>[pipeline.rs]"]
  node_lexer["Lexer<br/>[mod.rs]"]
  node_parser["Parser and AST<br/>[mod.rs]"]
  node_type_inference["Type inference<br/>[infer.rs]"]
  node_optimizer["Optimizer<br/>[optimizer.rs]"]
  node_compiler["Bytecode compiler<br/>[pipeline.rs]"]
  node_bytecode["Bytecode format<br/>[mod.rs]"]
  node_assembler["Assembler and disassembler<br/>[mod.rs]"]
end

subgraph group_runtime["Runtime"]
  node_vm["Register VM<br/>[core.rs]"]
  node_heap["Heap and GC<br/>[mod.rs]"]
  node_objects["Runtime values<br/>[mod.rs]"]
  node_jit["Cranelift JIT<br/>[mod.rs]"]
  node_stdlib["Standard library<br/>[mod.rs]"]
end

subgraph group_extensions["Modules and extensions"]
  node_module_loader["Module loader<br/>[mod.rs]"]
  node_module_resolution["Module resolution<br/>[mod.rs]"]
  node_native_abi["Native module ABI<br/>[lib.rs]"]
  node_native_macros["Native macros<br/>[lib.rs]"]
end

node_user(("Language user"))

node_user -->|"runs programs"| node_cli
node_user -->|"calls API"| node_public_api
node_cli -->|"dispatches commands"| node_driver
node_public_api -->|"delegates"| node_driver
node_repl -->|"submits input"| node_driver
node_driver -->|"executes pipeline"| node_pipeline
node_pipeline -->|"tokenizes"| node_lexer
node_pipeline -->|"parses"| node_parser
node_pipeline -->|"infers types"| node_type_inference
node_pipeline -->|"optimizes"| node_optimizer
node_pipeline -->|"compiles"| node_compiler
node_lexer -->|"tokens"| node_parser
node_parser -->|"AST"| node_type_inference
node_type_inference -->|"typed AST"| node_optimizer
node_optimizer -->|"optimized AST"| node_compiler
node_compiler -->|"emits bytecode"| node_bytecode
node_driver -->|"runs bytecode"| node_vm
node_assembler -->|"assembles"| node_bytecode
node_vm -->|"decodes"| node_bytecode
node_vm -->|"allocates and collects"| node_heap
node_vm -->|"operates on values"| node_objects
node_vm -->|"dispatches natives"| node_stdlib
node_vm -.->|"compiles hot code"| node_jit
node_driver -->|"loads imports"| node_module_loader
node_module_loader -->|"resolves modules"| node_module_resolution
node_module_loader -.->|"loads native modules"| node_native_abi
node_native_macros -->|"generates wrappers"| node_native_abi

click node_cli "https://github.com/vbxq/elyra/blob/master/cli/src/cli/commands/run.rs"
click node_public_api "https://github.com/vbxq/elyra/blob/master/aelys/src/api/mod.rs"
click node_repl "https://github.com/vbxq/elyra/blob/master/driver/src/api/repl.rs"
click node_driver "https://github.com/vbxq/elyra/blob/master/driver/src/api/mod.rs"
click node_pipeline "https://github.com/vbxq/elyra/blob/master/driver/src/pipeline/pipeline.rs"
click node_lexer "https://github.com/vbxq/elyra/blob/master/frontend/src/lexer/mod.rs"
click node_parser "https://github.com/vbxq/elyra/blob/master/frontend/src/parser/mod.rs"
click node_type_inference "https://github.com/vbxq/elyra/blob/master/sema/src/infer.rs"
click node_optimizer "https://github.com/vbxq/elyra/blob/master/opt/src/passes/optimizer.rs"
click node_compiler "https://github.com/vbxq/elyra/blob/master/backend/src/compiler/pipeline.rs"
click node_bytecode "https://github.com/vbxq/elyra/blob/master/bytecode/src/bytecode/mod.rs"
click node_assembler "https://github.com/vbxq/elyra/blob/master/bytecode/src/asm/mod.rs"
click node_vm "https://github.com/vbxq/elyra/blob/master/runtime/src/vm/core.rs"
click node_heap "https://github.com/vbxq/elyra/blob/master/bytecode/src/heap/mod.rs"
click node_objects "https://github.com/vbxq/elyra/blob/master/bytecode/src/object/mod.rs"
click node_jit "https://github.com/vbxq/elyra/blob/master/aelys/src/jit/mod.rs"
click node_stdlib "https://github.com/vbxq/elyra/blob/master/runtime/src/stdlib/mod.rs"
click node_module_loader "https://github.com/vbxq/elyra/blob/master/driver/src/modules/loader/mod.rs"
click node_module_resolution "https://github.com/vbxq/elyra/blob/master/modules/src/resolution/mod.rs"
click node_native_abi "https://github.com/vbxq/elyra/blob/master/native/src/lib.rs"
click node_native_macros "https://github.com/vbxq/elyra/blob/master/native-macros/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_public_api,node_repl,node_driver,node_user toneBlue
class node_pipeline,node_lexer,node_parser,node_type_inference,node_optimizer,node_compiler,node_bytecode,node_assembler toneAmber
class node_vm,node_heap,node_objects,node_jit,node_stdlib toneMint
class node_module_loader,node_module_resolution,node_native_abi,node_native_macros toneRose
```

## Components

### User interfaces

- [CLI commands](https://github.com/vbxq/elyra/blob/master/cli/src/cli/commands/run.rs): `cli/src/cli/commands/run.rs`
- [Public API](https://github.com/vbxq/elyra/blob/master/aelys/src/api/mod.rs): `aelys/src/api/mod.rs`
- [REPL](https://github.com/vbxq/elyra/blob/master/driver/src/api/repl.rs): `driver/src/api/repl.rs`
- [Driver API](https://github.com/vbxq/elyra/blob/master/driver/src/api/mod.rs): `driver/src/api/mod.rs`

### Compilation

- [Compile pipeline](https://github.com/vbxq/elyra/blob/master/driver/src/pipeline/pipeline.rs): `driver/src/pipeline/pipeline.rs`
- [Lexer](https://github.com/vbxq/elyra/blob/master/frontend/src/lexer/mod.rs): `frontend/src/lexer/mod.rs`
- [Parser and AST](https://github.com/vbxq/elyra/blob/master/frontend/src/parser/mod.rs): `frontend/src/parser/mod.rs`
- [Type inference](https://github.com/vbxq/elyra/blob/master/sema/src/infer.rs): `sema/src/infer.rs`
- [Optimizer](https://github.com/vbxq/elyra/blob/master/opt/src/passes/optimizer.rs): `opt/src/passes/optimizer.rs`
- [Bytecode compiler](https://github.com/vbxq/elyra/blob/master/backend/src/compiler/pipeline.rs): `backend/src/compiler/pipeline.rs`
- [Bytecode format](https://github.com/vbxq/elyra/blob/master/bytecode/src/bytecode/mod.rs): `bytecode/src/bytecode/mod.rs`
- [Assembler and disassembler](https://github.com/vbxq/elyra/blob/master/bytecode/src/asm/mod.rs): `bytecode/src/asm/mod.rs`

### Runtime

- [Register VM](https://github.com/vbxq/elyra/blob/master/runtime/src/vm/core.rs): `runtime/src/vm/core.rs`
- [Heap and GC](https://github.com/vbxq/elyra/blob/master/bytecode/src/heap/mod.rs): `bytecode/src/heap/mod.rs`
- [Runtime values](https://github.com/vbxq/elyra/blob/master/bytecode/src/object/mod.rs): `bytecode/src/object/mod.rs`
- [Cranelift JIT](https://github.com/vbxq/elyra/blob/master/aelys/src/jit/mod.rs): `aelys/src/jit/mod.rs`
- [Standard library](https://github.com/vbxq/elyra/blob/master/runtime/src/stdlib/mod.rs): `runtime/src/stdlib/mod.rs`

### Modules and extensions

- [Module loader](https://github.com/vbxq/elyra/blob/master/driver/src/modules/loader/mod.rs): `driver/src/modules/loader/mod.rs`
- [Module resolution](https://github.com/vbxq/elyra/blob/master/modules/src/resolution/mod.rs): `modules/src/resolution/mod.rs`
- [Native module ABI](https://github.com/vbxq/elyra/blob/master/native/src/lib.rs): `native/src/lib.rs`
- [Native macros](https://github.com/vbxq/elyra/blob/master/native-macros/src/lib.rs): `native-macros/src/lib.rs`

### Other components

- **Language user**

## Connections

- Language user → CLI commands: runs programs
- Language user → Public API: calls API
- CLI commands → Driver API: dispatches commands
- Public API → Driver API: delegates
- REPL → Driver API: submits input
- Driver API → Compile pipeline: executes pipeline
- Compile pipeline → Lexer: tokenizes
- Compile pipeline → Parser and AST: parses
- Compile pipeline → Type inference: infers types
- Compile pipeline → Optimizer: optimizes
- Compile pipeline → Bytecode compiler: compiles
- Lexer → Parser and AST: tokens
- Parser and AST → Type inference: AST
- Type inference → Optimizer: typed AST
- Optimizer → Bytecode compiler: optimized AST
- Bytecode compiler → Bytecode format: emits bytecode
- Driver API → Register VM: runs bytecode
- Assembler and disassembler → Bytecode format: assembles
- Register VM → Bytecode format: decodes
- Register VM → Heap and GC: allocates and collects
- Register VM → Runtime values: operates on values
- Register VM → Standard library: dispatches natives
- Register VM → Cranelift JIT: compiles hot code
- Driver API → Module loader: loads imports
- Module loader → Module resolution: resolves modules
- Module loader → Native module ABI: loads native modules
- Native macros → Native module ABI: generates wrappers