# rils-lang/rils architecture

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

- Interactive diagram: https://gitdiagram.com/rils-lang/rils
- Repository: https://github.com/rils-lang/rils

## Overview

Rils is an embeddable Rust-inspired scripting language. The main workflow runs from script or project input through lexing, parsing and semantic analysis, lowering and bytecode production, then execution by the interpreter or bytecode VM; results are returned to the caller. Separate branches cover project and library artifacts, host integration, and editor analysis. The README documents these capabilities; some implementation details and connections are inferred from module boundaries and package dependencies because their source was not sampled.

Main entry points: [`src/lib.rs`](https://github.com/rils-lang/rils/blob/main/src/lib.rs) (Rust Engine API), [`src/main.rs`](https://github.com/rils-lang/rils/blob/main/src/main.rs) (CLI and REPL), [`crates/rils_frontend/src/analysis.rs`](https://github.com/rils-lang/rils/blob/main/crates/rils_frontend/src/analysis.rs) (Semantic Analysis), [`crates/rils_frontend/src/lexer.rs`](https://github.com/rils-lang/rils/blob/main/crates/rils_frontend/src/lexer.rs) (Lexer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language Frontend"]
  node_lexer["Lexer<br/>[lexer.rs]"]
  node_parser["Parser<br/>[parser.rs]"]
  node_analysis["Semantic Analysis<br/>[analysis.rs]"]
  node_macros["Macro Expansion<br/>[macros.rs]"]
  node_builtins["Built-in Catalog<br/>[catalog.rs]"]
end

subgraph group_compilation["Compilation and Artifacts"]
  node_project["Project Model<br/>[lib.rs]"]
  node_hir["HIR Lowering<br/>[hir.rs]"]
  node_mir["MIR<br/>[mir.rs]"]
  node_bytecode["Bytecode Format<br/>[format.rs]"]
  node_verifier["Bytecode Verifier<br/>[verifier.rs]"]
  node_library["Library Artifacts<br/>[library.rs]"]
end

subgraph group_execution["Runtime Execution"]
  node_interpreter["Interpreter<br/>[interpreter.rs]"]
  node_vm["Bytecode VM<br/>[vm.rs]"]
  node_values["Runtime Values<br/>[value.rs]"]
end

subgraph group_integration["Embedding and Hosts"]
  node_api["Rust Engine API<br/>[lib.rs]"]
  node_host["Host Contracts<br/>[host.rs]"]
  node_capi["C ABI<br/>[lib.rs]"]
end

subgraph group_tools["Developer Tools"]
  node_cli["CLI and REPL<br/>[main.rs]"]
  node_analyzer["Language Server<br/>[main.rs]"]
  node_vscode["VS Code Extension<br/>[extension.js]"]
end

node_author(("Script Author"))
node_user(("Embedded Host"))

node_author -->|"submits scripts"| node_cli
node_author -->|"edits scripts"| node_vscode
node_vscode -.->|"LSP requests"| node_analyzer
node_cli -->|"loads project"| node_project
node_api -->|"loads project"| node_project
node_project -->|"provides sources"| node_lexer
node_cli -->|"compiles input"| node_lexer
node_api -->|"compiles source"| node_lexer
node_lexer -->|"tokens"| node_parser
node_parser -->|"expands macros"| node_macros
node_parser -->|"AST"| node_analysis
node_analysis -->|"resolves built-ins"| node_builtins
node_analysis -->|"typed program"| node_hir
node_hir -->|"lowers to MIR"| node_mir
node_mir -->|"encodes module"| node_bytecode
node_bytecode -->|"verifies module"| node_verifier
node_api -->|"evaluates source"| node_interpreter
node_api -->|"executes module"| node_vm
node_cli -->|"verifies files"| node_verifier
node_cli -->|"runs bytecode"| node_vm
node_api -->|"loads libraries"| node_library
node_vm -->|"produces values"| node_values
node_interpreter -->|"produces values"| node_values
node_user -->|"embeds runtime"| node_api
node_user -->|"calls C ABI"| node_capi
node_capi -->|"uses runtime"| node_api
node_host -->|"defines host ABI"| node_api
node_analyzer -->|"indexes workspace"| node_project
node_analyzer -->|"analyzes documents"| node_analysis

click node_project "https://github.com/rils-lang/rils/blob/main/crates/rils_project/src/lib.rs"
click node_lexer "https://github.com/rils-lang/rils/blob/main/crates/rils_frontend/src/lexer.rs"
click node_parser "https://github.com/rils-lang/rils/blob/main/crates/rils_frontend/src/parser.rs"
click node_analysis "https://github.com/rils-lang/rils/blob/main/crates/rils_frontend/src/analysis.rs"
click node_macros "https://github.com/rils-lang/rils/blob/main/crates/rils_frontend/src/macros.rs"
click node_builtins "https://github.com/rils-lang/rils/blob/main/crates/rils_builtins/src/catalog.rs"
click node_hir "https://github.com/rils-lang/rils/blob/main/crates/rils_compiler/src/hir.rs"
click node_mir "https://github.com/rils-lang/rils/blob/main/crates/rils_compiler/src/mir.rs"
click node_bytecode "https://github.com/rils-lang/rils/blob/main/src/bytecode/format.rs"
click node_verifier "https://github.com/rils-lang/rils/blob/main/src/bytecode/verifier.rs"
click node_library "https://github.com/rils-lang/rils/blob/main/src/library.rs"
click node_api "https://github.com/rils-lang/rils/blob/main/src/lib.rs"
click node_interpreter "https://github.com/rils-lang/rils/blob/main/src/interpreter.rs"
click node_vm "https://github.com/rils-lang/rils/blob/main/src/bytecode/vm.rs"
click node_values "https://github.com/rils-lang/rils/blob/main/src/value.rs"
click node_host "https://github.com/rils-lang/rils/blob/main/crates/rils_compiler/src/host.rs"
click node_capi "https://github.com/rils-lang/rils/blob/main/tools/rils-capi/src/lib.rs"
click node_cli "https://github.com/rils-lang/rils/blob/main/src/main.rs"
click node_analyzer "https://github.com/rils-lang/rils/blob/main/tools/rils-analyzer/src/main.rs"
click node_vscode "https://github.com/rils-lang/rils/blob/main/editors/vscode-rils/extension.js"

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_lexer,node_parser,node_analysis,node_macros,node_builtins toneBlue
class node_project,node_hir,node_mir,node_bytecode,node_verifier,node_library toneAmber
class node_interpreter,node_vm,node_values toneMint
class node_api,node_host,node_capi toneRose
class node_cli,node_analyzer,node_vscode,node_author,node_user toneIndigo
```

## Components

### Language Frontend

- [Lexer](https://github.com/rils-lang/rils/blob/main/crates/rils_frontend/src/lexer.rs): `crates/rils_frontend/src/lexer.rs`
- [Parser](https://github.com/rils-lang/rils/blob/main/crates/rils_frontend/src/parser.rs): `crates/rils_frontend/src/parser.rs`
- [Semantic Analysis](https://github.com/rils-lang/rils/blob/main/crates/rils_frontend/src/analysis.rs): `crates/rils_frontend/src/analysis.rs`
- [Macro Expansion](https://github.com/rils-lang/rils/blob/main/crates/rils_frontend/src/macros.rs): `crates/rils_frontend/src/macros.rs`
- [Built-in Catalog](https://github.com/rils-lang/rils/blob/main/crates/rils_builtins/src/catalog.rs): `crates/rils_builtins/src/catalog.rs`

### Compilation and Artifacts

- [Project Model](https://github.com/rils-lang/rils/blob/main/crates/rils_project/src/lib.rs): `crates/rils_project/src/lib.rs`
- [HIR Lowering](https://github.com/rils-lang/rils/blob/main/crates/rils_compiler/src/hir.rs): `crates/rils_compiler/src/hir.rs`
- [MIR](https://github.com/rils-lang/rils/blob/main/crates/rils_compiler/src/mir.rs): `crates/rils_compiler/src/mir.rs`
- [Bytecode Format](https://github.com/rils-lang/rils/blob/main/src/bytecode/format.rs): `src/bytecode/format.rs`
- [Bytecode Verifier](https://github.com/rils-lang/rils/blob/main/src/bytecode/verifier.rs): `src/bytecode/verifier.rs`
- [Library Artifacts](https://github.com/rils-lang/rils/blob/main/src/library.rs): `src/library.rs`

### Runtime Execution

- [Interpreter](https://github.com/rils-lang/rils/blob/main/src/interpreter.rs): `src/interpreter.rs`
- [Bytecode VM](https://github.com/rils-lang/rils/blob/main/src/bytecode/vm.rs): `src/bytecode/vm.rs`
- [Runtime Values](https://github.com/rils-lang/rils/blob/main/src/value.rs): `src/value.rs`

### Embedding and Hosts

- [Rust Engine API](https://github.com/rils-lang/rils/blob/main/src/lib.rs): `src/lib.rs`
- [Host Contracts](https://github.com/rils-lang/rils/blob/main/crates/rils_compiler/src/host.rs): `crates/rils_compiler/src/host.rs`
- [C ABI](https://github.com/rils-lang/rils/blob/main/tools/rils-capi/src/lib.rs): `tools/rils-capi/src/lib.rs`

### Developer Tools

- [CLI and REPL](https://github.com/rils-lang/rils/blob/main/src/main.rs): `src/main.rs`
- [Language Server](https://github.com/rils-lang/rils/blob/main/tools/rils-analyzer/src/main.rs): `tools/rils-analyzer/src/main.rs`
- [VS Code Extension](https://github.com/rils-lang/rils/blob/main/editors/vscode-rils/extension.js): `editors/vscode-rils/extension.js`

### Other components

- **Script Author**
- **Embedded Host**

## Connections

- Script Author → CLI and REPL: submits scripts
- Script Author → VS Code Extension: edits scripts
- VS Code Extension → Language Server: LSP requests
- CLI and REPL → Project Model: loads project
- Rust Engine API → Project Model: loads project
- Project Model → Lexer: provides sources
- CLI and REPL → Lexer: compiles input
- Rust Engine API → Lexer: compiles source
- Lexer → Parser: tokens
- Parser → Macro Expansion: expands macros
- Parser → Semantic Analysis: AST
- Semantic Analysis → Built-in Catalog: resolves built-ins
- Semantic Analysis → HIR Lowering: typed program
- HIR Lowering → MIR: lowers to MIR
- MIR → Bytecode Format: encodes module
- Bytecode Format → Bytecode Verifier: verifies module
- Rust Engine API → Interpreter: evaluates source
- Rust Engine API → Bytecode VM: executes module
- CLI and REPL → Bytecode Verifier: verifies files
- CLI and REPL → Bytecode VM: runs bytecode
- Rust Engine API → Library Artifacts: loads libraries
- Bytecode VM → Runtime Values: produces values
- Interpreter → Runtime Values: produces values
- Embedded Host → Rust Engine API: embeds runtime
- Embedded Host → C ABI: calls C ABI
- C ABI → Rust Engine API: uses runtime
- Host Contracts → Rust Engine API: defines host ABI
- Language Server → Project Model: indexes workspace
- Language Server → Semantic Analysis: analyzes documents