# expr-lang/expr architecture

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

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

## Overview

Expr is a Go expression language for safely compiling and evaluating expressions against Go-provided environments. The main workflow is expression input through parsing, static checking and optimization to bytecode, then VM evaluation and a result. Separate capabilities include built-ins, environment/type modeling, AST tools, context/operator patching, documentation generation, debugging and an interactive REPL. The workflow links are grounded in the README and SOURCE INDEX references; unsampled implementation details are not expanded into additional call edges.

Main entry points: [`expr.go`](https://github.com/expr-lang/expr/blob/master/expr.go) (Expr API), [`parser/parser.go`](https://github.com/expr-lang/expr/blob/master/parser/parser.go) (Parser), [`checker/checker.go`](https://github.com/expr-lang/expr/blob/master/checker/checker.go) (Type Checker), [`vm/vm.go`](https://github.com/expr-lang/expr/blob/master/vm/vm.go) (Virtual Machine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language Front End"]
  node_api["Expr API<br/>[expr.go]"]
  node_parser["Parser<br/>[parser.go]"]
  node_lexer["Lexer<br/>[lexer.go]"]
  node_ast["Expression AST<br/>[node.go]"]
  node_checker["Type Checker<br/>[checker.go]"]
  node_nature["Type Model<br/>[nature.go]"]
end

subgraph group_execution["Compilation and Runtime"]
  node_optimizer["Optimizer<br/>[fold.go]"]
  node_compiler["Bytecode Compiler<br/>[compiler.go]"]
  node_program["Bytecode Program<br/>[program.go]"]
  node_vm["Virtual Machine<br/>[vm.go]"]
  node_runtime["Runtime Helpers<br/>[runtime.go]"]
end

subgraph group_extensions["Language Extensions"]
  node_builtins["Built-in Functions<br/>[builtin.go]"]
  node_config["Environment Config<br/>[env.go]"]
  node_patching["Expression Patching<br/>[with_context.go]"]
end

subgraph group_tools["Developer Tools"]
  node_docgen["Type Documentation<br/>[docgen.go]"]
  node_debugger["VM Debugger<br/>[debugger.go]"]
  node_repl["Interactive REPL<br/>[repl.go]"]
end

node_user(("Go Caller"))
node_result(("Evaluation Result"))

node_user -->|"supplies expression"| node_api
node_api -->|"parses input"| node_parser
node_parser -->|"reads tokens"| node_lexer
node_parser -.->|"builds tree"| node_ast
node_api -->|"type-checks"| node_checker
node_checker -->|"uses type model"| node_nature
node_api -->|"optimizes tree"| node_optimizer
node_api -->|"compiles expression"| node_compiler
node_compiler -->|"emits bytecode"| node_program
node_api -->|"runs program"| node_vm
node_vm -->|"uses helpers"| node_runtime
node_builtins -->|"uses helpers"| node_runtime
node_config -.->|"provides environment types"| node_checker
node_api -->|"returns evaluation"| node_result
node_user -.->|"requests type docs"| node_docgen
node_user -.->|"starts debugging"| node_debugger
node_debugger -->|"inspects program"| node_vm
node_user -->|"enters expressions"| node_repl
node_repl -->|"compiles and runs"| node_api
node_user -.->|"configures patches"| node_patching
node_patching -->|"rewrites calls"| node_ast

click node_api "https://github.com/expr-lang/expr/blob/master/expr.go"
click node_parser "https://github.com/expr-lang/expr/blob/master/parser/parser.go"
click node_lexer "https://github.com/expr-lang/expr/blob/master/parser/lexer/lexer.go"
click node_ast "https://github.com/expr-lang/expr/blob/master/ast/node.go"
click node_checker "https://github.com/expr-lang/expr/blob/master/checker/checker.go"
click node_nature "https://github.com/expr-lang/expr/blob/master/checker/nature/nature.go"
click node_optimizer "https://github.com/expr-lang/expr/blob/master/optimizer/fold.go"
click node_compiler "https://github.com/expr-lang/expr/blob/master/compiler/compiler.go"
click node_program "https://github.com/expr-lang/expr/blob/master/vm/program.go"
click node_vm "https://github.com/expr-lang/expr/blob/master/vm/vm.go"
click node_runtime "https://github.com/expr-lang/expr/blob/master/vm/runtime/runtime.go"
click node_builtins "https://github.com/expr-lang/expr/blob/master/builtin/builtin.go"
click node_config "https://github.com/expr-lang/expr/blob/master/conf/env.go"
click node_patching "https://github.com/expr-lang/expr/blob/master/patcher/with_context.go"
click node_docgen "https://github.com/expr-lang/expr/blob/master/docgen/docgen.go"
click node_debugger "https://github.com/expr-lang/expr/blob/master/debug/debugger.go"
click node_repl "https://github.com/expr-lang/expr/blob/master/repl/repl.go"

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_api,node_parser,node_lexer,node_ast,node_checker,node_nature toneBlue
class node_optimizer,node_compiler,node_program,node_vm,node_runtime toneAmber
class node_builtins,node_config,node_patching toneMint
class node_docgen,node_debugger,node_repl toneRose
class node_user,node_result toneIndigo
```

## Components

### Language Front End

- [Expr API](https://github.com/expr-lang/expr/blob/master/expr.go): `expr.go`
- [Parser](https://github.com/expr-lang/expr/blob/master/parser/parser.go): `parser/parser.go`
- [Lexer](https://github.com/expr-lang/expr/blob/master/parser/lexer/lexer.go): `parser/lexer/lexer.go`
- [Expression AST](https://github.com/expr-lang/expr/blob/master/ast/node.go): `ast/node.go`
- [Type Checker](https://github.com/expr-lang/expr/blob/master/checker/checker.go): `checker/checker.go`
- [Type Model](https://github.com/expr-lang/expr/blob/master/checker/nature/nature.go): `checker/nature/nature.go`

### Compilation and Runtime

- [Optimizer](https://github.com/expr-lang/expr/blob/master/optimizer/fold.go): `optimizer/fold.go`
- [Bytecode Compiler](https://github.com/expr-lang/expr/blob/master/compiler/compiler.go): `compiler/compiler.go`
- [Bytecode Program](https://github.com/expr-lang/expr/blob/master/vm/program.go): `vm/program.go`
- [Virtual Machine](https://github.com/expr-lang/expr/blob/master/vm/vm.go): `vm/vm.go`
- [Runtime Helpers](https://github.com/expr-lang/expr/blob/master/vm/runtime/runtime.go): `vm/runtime/runtime.go`

### Language Extensions

- [Built-in Functions](https://github.com/expr-lang/expr/blob/master/builtin/builtin.go): `builtin/builtin.go`
- [Environment Config](https://github.com/expr-lang/expr/blob/master/conf/env.go): `conf/env.go`
- [Expression Patching](https://github.com/expr-lang/expr/blob/master/patcher/with_context.go): `patcher/with_context.go`

### Developer Tools

- [Type Documentation](https://github.com/expr-lang/expr/blob/master/docgen/docgen.go): `docgen/docgen.go`
- [VM Debugger](https://github.com/expr-lang/expr/blob/master/debug/debugger.go): `debug/debugger.go`
- [Interactive REPL](https://github.com/expr-lang/expr/blob/master/repl/repl.go): `repl/repl.go`

### Other components

- **Go Caller**
- **Evaluation Result**

## Connections

- Go Caller → Expr API: supplies expression (evidence: `README.md`)
- Expr API → Parser: parses input (evidence: `expr.go`)
- Parser → Lexer: reads tokens (evidence: `parser/parser.go`)
- Parser → Expression AST: builds tree
- Expr API → Type Checker: type-checks (evidence: `expr.go`)
- Type Checker → Type Model: uses type model (evidence: `checker/checker.go`)
- Expr API → Optimizer: optimizes tree (evidence: `expr.go`)
- Expr API → Bytecode Compiler: compiles expression (evidence: `expr.go`)
- Bytecode Compiler → Bytecode Program: emits bytecode (evidence: `compiler/compiler.go`)
- Expr API → Virtual Machine: runs program (evidence: `expr.go`)
- Virtual Machine → Runtime Helpers: uses helpers (evidence: `vm/vm.go`)
- Built-in Functions → Runtime Helpers: uses helpers (evidence: `builtin/builtin.go`)
- Environment Config → Type Checker: provides environment types
- Expr API → Evaluation Result: returns evaluation (evidence: `README.md`)
- Go Caller → Type Documentation: requests type docs
- Go Caller → VM Debugger: starts debugging
- VM Debugger → Virtual Machine: inspects program (evidence: `debug/debugger.go`)
- Go Caller → Interactive REPL: enters expressions (evidence: `repl/repl.go`)
- Interactive REPL → Expr API: compiles and runs (evidence: `repl/repl.go`)
- Go Caller → Expression Patching: configures patches
- Expression Patching → Expression AST: rewrites calls (evidence: `patcher/with_context.go`)
