# phreda4/r3evm architecture

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

- Interactive diagram: https://gitdiagram.com/phreda4/r3evm
- Repository: https://github.com/phreda4/r3evm

## Overview

r3 is a Forth-family concatenative language VM. Its principal workflow is to load a source program, tokenize and compile it into dwordcode, then interpret that code. The README specifically documents automatic constant folding, short-word inlining, tail calls, and hidden optimized tokens, as well as dynamic-library calls for OS access. The sampled C++ source supports the compile/run and syscall boundaries; other library and tool directories are shown as capabilities, without asserting unsampled call wiring.

Main entry points: [`r3.cpp`](https://github.com/phreda4/r3evm/blob/main/r3.cpp) (VM interpreter), [`main.r3`](https://github.com/phreda4/r3evm/blob/main/main.r3) (R3 program)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compile["Compile pipeline"]
  node_compiler["Source compiler<br/>[r3.cpp]"]
  node_tokenizer["Tokenizer<br/>[r3.cpp]"]
  node_optimizer["Token optimizer<br/>[r3.cpp]"]
  node_bytecode["Dwordcode<br/>[r3.cpp]"]
end

subgraph group_runtime["VM runtime"]
  node_vm["VM interpreter<br/>[r3.cpp]"]
  node_stacks["Data and return stacks<br/>[r3.cpp]"]
  node_dynamic["Dynamic calls<br/>[r3.cpp]"]
end

subgraph group_ecosystem["Language ecosystem"]
  node_r3system["R3 system modules"]
  node_r3ide["IDE and tools"]
  node_libraries["Language libraries"]
  node_utilities["Utilities"]
  node_examples["Terminal examples"]
end

node_user(("Program author"))
node_program["R3 program<br/>[main.r3]"]
node_os{{"Host OS libraries"}}

node_user -->|"writes"| node_program
node_program -->|"loads source"| node_compiler
node_compiler -->|"tokenizes"| node_tokenizer
node_tokenizer -->|"optimizes tokens"| node_optimizer
node_optimizer -->|"emits code"| node_bytecode
node_compiler -->|"starts execution"| node_vm
node_bytecode -->|"executes"| node_vm
node_vm -->|"uses"| node_stacks
node_vm -->|"dispatches calls"| node_dynamic
node_dynamic -->|"loads and calls"| node_os

click node_program "https://github.com/phreda4/r3evm/blob/main/main.r3"
click node_compiler "https://github.com/phreda4/r3evm/blob/main/r3.cpp"
click node_tokenizer "https://github.com/phreda4/r3evm/blob/main/r3.cpp"
click node_optimizer "https://github.com/phreda4/r3evm/blob/main/r3.cpp"
click node_bytecode "https://github.com/phreda4/r3evm/blob/main/r3.cpp"
click node_vm "https://github.com/phreda4/r3evm/blob/main/r3.cpp"
click node_stacks "https://github.com/phreda4/r3evm/blob/main/r3.cpp"
click node_dynamic "https://github.com/phreda4/r3evm/blob/main/r3.cpp"
click node_r3system "https://github.com/phreda4/r3evm/tree/main/r3/system"
click node_r3ide "https://github.com/phreda4/r3evm/tree/main/r3/d4"
click node_libraries "https://github.com/phreda4/r3evm/tree/main/r3/lib"
click node_utilities "https://github.com/phreda4/r3evm/tree/main/r3/util"
click node_examples "https://github.com/phreda4/r3evm/tree/main/r3/term"

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_compiler,node_tokenizer,node_optimizer,node_bytecode toneBlue
class node_vm,node_stacks,node_dynamic toneAmber
class node_r3system,node_r3ide,node_libraries,node_utilities,node_examples toneMint
class node_user,node_os toneIndigo
class node_program toneTeal
```

## Components

### Compile pipeline

- [Source compiler](https://github.com/phreda4/r3evm/blob/main/r3.cpp): `r3.cpp`
- [Tokenizer](https://github.com/phreda4/r3evm/blob/main/r3.cpp): `r3.cpp`
- [Token optimizer](https://github.com/phreda4/r3evm/blob/main/r3.cpp): `r3.cpp`
- [Dwordcode](https://github.com/phreda4/r3evm/blob/main/r3.cpp): `r3.cpp`

### VM runtime

- [VM interpreter](https://github.com/phreda4/r3evm/blob/main/r3.cpp): `r3.cpp`
- [Data and return stacks](https://github.com/phreda4/r3evm/blob/main/r3.cpp): `r3.cpp`
- [Dynamic calls](https://github.com/phreda4/r3evm/blob/main/r3.cpp): `r3.cpp`

### Language ecosystem

- [R3 system modules](https://github.com/phreda4/r3evm/tree/main/r3/system): `r3/system`
- [IDE and tools](https://github.com/phreda4/r3evm/tree/main/r3/d4): `r3/d4`
- [Language libraries](https://github.com/phreda4/r3evm/tree/main/r3/lib): `r3/lib`
- [Utilities](https://github.com/phreda4/r3evm/tree/main/r3/util): `r3/util`
- [Terminal examples](https://github.com/phreda4/r3evm/tree/main/r3/term): `r3/term`

### Other components

- **Program author**
- [R3 program](https://github.com/phreda4/r3evm/blob/main/main.r3): `main.r3`
- **Host OS libraries**

## Connections

- Program author → R3 program: writes
- R3 program → Source compiler: loads source
- Source compiler → Tokenizer: tokenizes
- Tokenizer → Token optimizer: optimizes tokens
- Token optimizer → Dwordcode: emits code
- Source compiler → VM interpreter: starts execution
- Dwordcode → VM interpreter: executes
- VM interpreter → Data and return stacks: uses
- VM interpreter → Dynamic calls: dispatches calls
- Dynamic calls → Host OS libraries: loads and calls