# valkmjolnir/nasal-interpreter architecture

> Architecture diagram of the GitHub repository valkmjolnir/nasal-interpreter, 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/valkmjolnir/nasal-interpreter
- Repository: https://github.com/valkmjolnir/nasal-interpreter

## Overview

Nasal is a C++ interpreter for an ECMAScript-like scripting language, intended for standalone scripting and FlightGear-related debugging. Its principal workflow takes a script from the CLI through lexing, parsing, import linking, AST optimization and bytecode generation, then executes it in a VM or debugger. The repository also provides an interactive REPL, native libraries, formatting and linting tools, loadable modules, and a web evaluation interface. The main workflow is explicit in `src/main.cpp`; unsampled subsystem wiring is shown only where documented or evident from the available files.

Main entry points: [`src/main.cpp`](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/main.cpp) (CLI entry), [`src/vm/vm.cpp`](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/vm/vm.cpp) (Virtual machine), [`src/code/compilation.cpp`](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/code/compilation.cpp) (Compiled program), [`src/lexer/lexer.cpp`](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/lexer/lexer.cpp) (Lexer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language pipeline"]
  node_lexer["Lexer<br/>[lexer.cpp]"]
  node_parser["Parser<br/>[parse.cpp]"]
  node_linker["Import linker<br/>[linker.cpp]"]
  node_optimizer["AST optimizer<br/>[optimizer.cpp]"]
  node_codegen["Bytecode generator<br/>[codegen.cpp]"]
  node_compilation["Compiled program<br/>[compilation.cpp]"]
end

subgraph group_runtime["Execution runtime"]
  node_vm["Virtual machine<br/>[vm.cpp]"]
  node_debugger["Debugger<br/>[dbg.cpp]"]
  node_gc["Garbage collector<br/>[gc.cpp]"]
  node_native_registry["Native registry<br/>[registry.cpp]"]
end

subgraph group_interfaces["User interfaces"]
  node_main["CLI entry<br/>[main.cpp]"]
  node_repl["Interactive REPL<br/>[repl.cpp]"]
  node_web_server["Web server<br/>[server.js]"]
  node_web_client["Web client<br/>[repl.js]"]
  node_web_api["Web evaluation API<br/>[web.cpp]"]
end

subgraph group_extensions["Libraries and tools"]
  node_native_libs["Native libraries"]
  node_modules["Loadable modules"]
  node_formatter["Source formatter<br/>[main.cpp]"]
  node_linter["Source linter<br/>[main.cpp]"]
end

node_cli_user(("CLI user"))
node_browser_user(("Browser user"))

node_cli_user -->|"invokes"| node_main
node_main -->|"scans source"| node_lexer
node_lexer -->|"provides tokens"| node_parser
node_parser -->|"provides AST"| node_linker
node_linker -->|"provides linked AST"| node_optimizer
node_optimizer -->|"provides optimized AST"| node_codegen
node_codegen -->|"emits bytecode"| node_compilation
node_main -->|"runs program"| node_vm
node_main -->|"runs debug session"| node_debugger
node_vm -->|"executes bytecode"| node_compilation
node_debugger -->|"debugs bytecode"| node_compilation
node_vm -->|"allocates and collects"| node_gc
node_vm -->|"uses native functions"| node_native_registry
node_native_registry -->|"registers builtins"| node_native_libs
node_main -->|"starts REPL"| node_repl
node_browser_user -->|"submits code"| node_web_client
node_web_client -->|"sends evaluation"| node_web_server
node_web_server -->|"calls native API"| node_web_api
node_web_api -->|"evaluates code"| node_vm
node_cli_user -->|"formats source"| node_formatter
node_cli_user -->|"checks source"| node_linter
node_native_libs -.->|"supports extensions"| node_modules

click node_main "https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/main.cpp"
click node_repl "https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/repl/repl.cpp"
click node_web_server "https://github.com/valkmjolnir/nasal-interpreter/blob/master/nasal-web-app/server.js"
click node_web_client "https://github.com/valkmjolnir/nasal-interpreter/blob/master/nasal-web-app/public/repl.js"
click node_web_api "https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/web/web.cpp"
click node_lexer "https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/lexer/lexer.cpp"
click node_parser "https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/parse/parse.cpp"
click node_linker "https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/parse/linker.cpp"
click node_optimizer "https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/ast/optimizer.cpp"
click node_codegen "https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/code/codegen.cpp"
click node_compilation "https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/code/compilation.cpp"
click node_vm "https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/vm/vm.cpp"
click node_debugger "https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/dbg/dbg.cpp"
click node_gc "https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/vm/gc.cpp"
click node_native_registry "https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/natives/registry.cpp"
click node_native_libs "https://github.com/valkmjolnir/nasal-interpreter/tree/master/src/natives"
click node_modules "https://github.com/valkmjolnir/nasal-interpreter/tree/master/module"
click node_formatter "https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/tools/format/main.cpp"
click node_linter "https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/tools/linter/main.cpp"

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_linker,node_optimizer,node_codegen,node_compilation,node_cli_user,node_browser_user toneBlue
class node_vm,node_debugger,node_gc,node_native_registry toneAmber
class node_main,node_repl,node_web_server,node_web_client,node_web_api toneMint
class node_native_libs,node_modules,node_formatter,node_linter toneRose
```

## Components

### Language pipeline

- [Lexer](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/lexer/lexer.cpp): `src/lexer/lexer.cpp`
- [Parser](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/parse/parse.cpp): `src/parse/parse.cpp`
- [Import linker](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/parse/linker.cpp): `src/parse/linker.cpp`
- [AST optimizer](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/ast/optimizer.cpp): `src/ast/optimizer.cpp`
- [Bytecode generator](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/code/codegen.cpp): `src/code/codegen.cpp`
- [Compiled program](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/code/compilation.cpp): `src/code/compilation.cpp`

### Execution runtime

- [Virtual machine](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/vm/vm.cpp): `src/vm/vm.cpp`
- [Debugger](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/dbg/dbg.cpp): `src/dbg/dbg.cpp`
- [Garbage collector](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/vm/gc.cpp): `src/vm/gc.cpp`
- [Native registry](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/natives/registry.cpp): `src/natives/registry.cpp`

### User interfaces

- [CLI entry](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/main.cpp): `src/main.cpp`
- [Interactive REPL](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/repl/repl.cpp): `src/repl/repl.cpp`
- [Web server](https://github.com/valkmjolnir/nasal-interpreter/blob/master/nasal-web-app/server.js): `nasal-web-app/server.js`
- [Web client](https://github.com/valkmjolnir/nasal-interpreter/blob/master/nasal-web-app/public/repl.js): `nasal-web-app/public/repl.js`
- [Web evaluation API](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/web/web.cpp): `src/web/web.cpp`

### Libraries and tools

- [Native libraries](https://github.com/valkmjolnir/nasal-interpreter/tree/master/src/natives): `src/natives`
- [Loadable modules](https://github.com/valkmjolnir/nasal-interpreter/tree/master/module): `module`
- [Source formatter](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/tools/format/main.cpp): `src/tools/format/main.cpp`
- [Source linter](https://github.com/valkmjolnir/nasal-interpreter/blob/master/src/tools/linter/main.cpp): `src/tools/linter/main.cpp`

### Other components

- **CLI user**
- **Browser user**

## Connections

- CLI user → CLI entry: invokes
- CLI entry → Lexer: scans source
- Lexer → Parser: provides tokens
- Parser → Import linker: provides AST
- Import linker → AST optimizer: provides linked AST
- AST optimizer → Bytecode generator: provides optimized AST
- Bytecode generator → Compiled program: emits bytecode
- CLI entry → Virtual machine: runs program
- CLI entry → Debugger: runs debug session
- Virtual machine → Compiled program: executes bytecode
- Debugger → Compiled program: debugs bytecode
- Virtual machine → Garbage collector: allocates and collects
- Virtual machine → Native registry: uses native functions
- Native registry → Native libraries: registers builtins
- CLI entry → Interactive REPL: starts REPL
- Browser user → Web client: submits code
- Web client → Web server: sends evaluation
- Web server → Web evaluation API: calls native API
- Web evaluation API → Virtual machine: evaluates code
- CLI user → Source formatter: formats source
- CLI user → Source linter: checks source
- Native libraries → Loadable modules: supports extensions