# luau-lang/lute architecture

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

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

## Overview

Lute is a standalone Luau runtime with a CLI and embedded Luau libraries. A typical user runs a Luau program through the CLI; the program can use runtime APIs for filesystem, networking, processes, and other general-purpose tasks, while tooling can inspect or manipulate Luau source. The README establishes the product capabilities, and sampled sources confirm the CLI entry point and selected network, filesystem, syntax, and debug behavior. Unsampled module registration and several subsystem call relationships are intentionally not inferred.

Main entry points: [`lute/runtime/src/runtime.cpp`](https://github.com/luau-lang/lute/blob/primary/lute/runtime/src/runtime.cpp) (Runtime core), [`lute/cli/src/climain.cpp`](https://github.com/luau-lang/lute/blob/primary/lute/cli/src/climain.cpp) (CLI commands), [`lute/net/src/net.cpp`](https://github.com/luau-lang/lute/blob/primary/lute/net/src/net.cpp) (Networking), [`lute/cli/src/main.cpp`](https://github.com/luau-lang/lute/blob/primary/lute/cli/src/main.cpp) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Execution"]
  node_cli["CLI entry<br/>[main.cpp]"]
  node_cli_main["CLI commands<br/>[climain.cpp]"]
  node_compile["Compile<br/>[compile.cpp]"]
  node_package_run["Package run<br/>[packagerun.cpp]"]
end

subgraph group_runtime["Runtime APIs"]
  node_runtime_core["Runtime core<br/>[runtime.cpp]"]
  node_require["Module require<br/>[require.cpp]"]
  node_filesystem["Filesystem<br/>[fs.cpp]"]
  node_network["Networking<br/>[net.cpp]"]
  node_http_client["HTTP client<br/>[httpclient.cpp]"]
  node_websocket_client["WebSocket client<br/>[wsclient.cpp]"]
  node_http_server["HTTP server<br/>[server.cpp]"]
  node_process["Processes<br/>[process.cpp]"]
  node_system["System APIs<br/>[system.cpp]"]
  node_io["I/O APIs<br/>[io.cpp]"]
  node_time["Time APIs<br/>[time.cpp]"]
end

subgraph group_libraries["Luau Libraries"]
  node_std["Standard library<br/>[stdlib.cpp]"]
  node_batteries["Batteries<br/>[clibatteries.cpp]"]
end

subgraph group_tooling["Developer Tooling"]
  node_syntax["Syntax parser<br/>[parser.cpp]"]
  node_type["Type serialization<br/>[type.cpp]"]
  node_debug["Debugger<br/>[debuginternals.cpp]"]
end

node_user(("Luau user"))

node_user -->|"runs program"| node_cli
node_cli -->|"dispatches to"| node_cli_main
node_cli_main -->|"compiles"| node_compile
node_cli_main -->|"runs package"| node_package_run
node_cli_main -->|"executes with"| node_runtime_core
node_runtime_core -->|"loads modules"| node_require
node_runtime_core -->|"exposes file APIs"| node_filesystem
node_runtime_core -->|"exposes network APIs"| node_network
node_network -->|"provides client"| node_http_client
node_network -->|"provides client"| node_websocket_client
node_network -->|"provides server"| node_http_server
node_runtime_core -->|"exposes process APIs"| node_process
node_runtime_core -->|"exposes system APIs"| node_system
node_runtime_core -->|"exposes I/O APIs"| node_io
node_runtime_core -->|"exposes time APIs"| node_time
node_runtime_core -->|"embeds library"| node_std
node_runtime_core -->|"embeds libraries"| node_batteries
node_user -->|"uses tooling"| node_syntax
node_user -->|"uses tooling"| node_type
node_user -->|"debugs programs"| node_debug

click node_cli "https://github.com/luau-lang/lute/blob/primary/lute/cli/src/main.cpp"
click node_cli_main "https://github.com/luau-lang/lute/blob/primary/lute/cli/src/climain.cpp"
click node_compile "https://github.com/luau-lang/lute/blob/primary/lute/cli/src/compile.cpp"
click node_package_run "https://github.com/luau-lang/lute/blob/primary/lute/cli/src/packagerun.cpp"
click node_runtime_core "https://github.com/luau-lang/lute/blob/primary/lute/runtime/src/runtime.cpp"
click node_require "https://github.com/luau-lang/lute/blob/primary/lute/require/src/require.cpp"
click node_filesystem "https://github.com/luau-lang/lute/blob/primary/lute/fs/src/fs.cpp"
click node_network "https://github.com/luau-lang/lute/blob/primary/lute/net/src/net.cpp"
click node_http_client "https://github.com/luau-lang/lute/blob/primary/lute/net/src/httpclient.cpp"
click node_websocket_client "https://github.com/luau-lang/lute/blob/primary/lute/net/src/wsclient.cpp"
click node_http_server "https://github.com/luau-lang/lute/blob/primary/lute/net/src/server.cpp"
click node_process "https://github.com/luau-lang/lute/blob/primary/lute/process/src/process.cpp"
click node_system "https://github.com/luau-lang/lute/blob/primary/lute/system/src/system.cpp"
click node_io "https://github.com/luau-lang/lute/blob/primary/lute/io/src/io.cpp"
click node_time "https://github.com/luau-lang/lute/blob/primary/lute/time/src/time.cpp"
click node_std "https://github.com/luau-lang/lute/blob/primary/lute/std/src/stdlib.cpp"
click node_batteries "https://github.com/luau-lang/lute/blob/primary/lute/batteries/src/clibatteries.cpp"
click node_syntax "https://github.com/luau-lang/lute/blob/primary/lute/syntax/src/parser.cpp"
click node_type "https://github.com/luau-lang/lute/blob/primary/lute/luau/src/type.cpp"
click node_debug "https://github.com/luau-lang/lute/blob/primary/lute/debug/src/debuginternals.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_cli,node_cli_main,node_compile,node_package_run,node_user toneBlue
class node_runtime_core,node_require,node_filesystem,node_network,node_http_client,node_websocket_client,node_http_server,node_process,node_system,node_io,node_time toneAmber
class node_std,node_batteries toneMint
class node_syntax,node_type,node_debug toneRose
```

## Components

### Execution

- [CLI entry](https://github.com/luau-lang/lute/blob/primary/lute/cli/src/main.cpp): `lute/cli/src/main.cpp`
- [CLI commands](https://github.com/luau-lang/lute/blob/primary/lute/cli/src/climain.cpp): `lute/cli/src/climain.cpp`
- [Compile](https://github.com/luau-lang/lute/blob/primary/lute/cli/src/compile.cpp): `lute/cli/src/compile.cpp`
- [Package run](https://github.com/luau-lang/lute/blob/primary/lute/cli/src/packagerun.cpp): `lute/cli/src/packagerun.cpp`

### Runtime APIs

- [Runtime core](https://github.com/luau-lang/lute/blob/primary/lute/runtime/src/runtime.cpp): `lute/runtime/src/runtime.cpp`
- [Module require](https://github.com/luau-lang/lute/blob/primary/lute/require/src/require.cpp): `lute/require/src/require.cpp`
- [Filesystem](https://github.com/luau-lang/lute/blob/primary/lute/fs/src/fs.cpp): `lute/fs/src/fs.cpp`
- [Networking](https://github.com/luau-lang/lute/blob/primary/lute/net/src/net.cpp): `lute/net/src/net.cpp`
- [HTTP client](https://github.com/luau-lang/lute/blob/primary/lute/net/src/httpclient.cpp): `lute/net/src/httpclient.cpp`
- [WebSocket client](https://github.com/luau-lang/lute/blob/primary/lute/net/src/wsclient.cpp): `lute/net/src/wsclient.cpp`
- [HTTP server](https://github.com/luau-lang/lute/blob/primary/lute/net/src/server.cpp): `lute/net/src/server.cpp`
- [Processes](https://github.com/luau-lang/lute/blob/primary/lute/process/src/process.cpp): `lute/process/src/process.cpp`
- [System APIs](https://github.com/luau-lang/lute/blob/primary/lute/system/src/system.cpp): `lute/system/src/system.cpp`
- [I/O APIs](https://github.com/luau-lang/lute/blob/primary/lute/io/src/io.cpp): `lute/io/src/io.cpp`
- [Time APIs](https://github.com/luau-lang/lute/blob/primary/lute/time/src/time.cpp): `lute/time/src/time.cpp`

### Luau Libraries

- [Standard library](https://github.com/luau-lang/lute/blob/primary/lute/std/src/stdlib.cpp): `lute/std/src/stdlib.cpp`
- [Batteries](https://github.com/luau-lang/lute/blob/primary/lute/batteries/src/clibatteries.cpp): `lute/batteries/src/clibatteries.cpp`

### Developer Tooling

- [Syntax parser](https://github.com/luau-lang/lute/blob/primary/lute/syntax/src/parser.cpp): `lute/syntax/src/parser.cpp`
- [Type serialization](https://github.com/luau-lang/lute/blob/primary/lute/luau/src/type.cpp): `lute/luau/src/type.cpp`
- [Debugger](https://github.com/luau-lang/lute/blob/primary/lute/debug/src/debuginternals.cpp): `lute/debug/src/debuginternals.cpp`

### Other components

- **Luau user**

## Connections

- Luau user → CLI entry: runs program
- CLI entry → CLI commands: dispatches to
- CLI commands → Compile: compiles
- CLI commands → Package run: runs package
- CLI commands → Runtime core: executes with
- Runtime core → Module require: loads modules
- Runtime core → Filesystem: exposes file APIs
- Runtime core → Networking: exposes network APIs
- Networking → HTTP client: provides client
- Networking → WebSocket client: provides client
- Networking → HTTP server: provides server
- Runtime core → Processes: exposes process APIs
- Runtime core → System APIs: exposes system APIs
- Runtime core → I/O APIs: exposes I/O APIs
- Runtime core → Time APIs: exposes time APIs
- Runtime core → Standard library: embeds library
- Runtime core → Batteries: embeds libraries
- Luau user → Syntax parser: uses tooling
- Luau user → Type serialization: uses tooling
- Luau user → Debugger: debugs programs
