# makepad/relax architecture

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

- Interactive diagram: https://gitdiagram.com/makepad/relax
- Repository: https://github.com/makepad/relax

## Overview

Relax is an experimental Rust live compiler and JIT for the edit-run loop. A user runs or tests a Cargo package; Relax parses and checks it, JIT-compiles functions on demand, and can patch edits into the running process. The process also answers inspection requests for profiling, debugging, hangs, and memory. The README documents these capabilities, while sampled source confirms portions of the compiler, inspection, and remote-command paths; unsampled subsystems are represented at their exact source paths without asserting internal call chains.

Main entry points: [`libs/relax/front/src/program.rs`](https://github.com/makepad/relax/blob/main/libs/relax/front/src/program.rs) (Program model), [`tools/run/runner/src/lib.rs`](https://github.com/makepad/relax/blob/main/tools/run/runner/src/lib.rs) (Runner CLI), [`libs/relax/compiler/src/serve.rs`](https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/serve.rs) (Runtime service), [`libs/relax/compiler/src/inspect/client.rs`](https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/inspect/client.rs) (Inspect client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Run and compile"]
  node_runner["Runner CLI<br/>[lib.rs]"]
  node_domain["Compiler domain<br/>[domain.rs]"]
  node_jit["JIT compilation<br/>[jit.rs]"]
  node_run["Program runtime<br/>[run.rs]"]
end

subgraph group_language["Rust front end"]
  node_program["Program model<br/>[program.rs]"]
  node_parser["Rust parser<br/>[parser.rs]"]
  node_definitions["Definition collection<br/>[def_collector.rs]"]
  node_macros["Macro expansion<br/>[macros.rs]"]
  node_builtins["Language builtins<br/>[builtins.rs]"]
  node_checker["Type checking<br/>[check.rs]"]
end

subgraph group_live["Live process"]
  node_serve["Runtime service<br/>[serve.rs]"]
  node_reload["Live reload<br/>[reload.rs]"]
  node_owner["Code ownership<br/>[owner.rs]"]
end

subgraph group_inspect["Inspection"]
  node_instrument["Runtime instrumentation<br/>[instrument.rs]"]
  node_threads["Thread inspection<br/>[threads.rs]"]
  node_timeline["Event timeline<br/>[timeline.rs]"]
  node_heap["Heap inspection<br/>[heap.rs]"]
  node_profmodel["Profile model<br/>[model.rs]"]
  node_inspectclient["Inspect client<br/>[client.rs]"]
end

subgraph group_remote["Remote access"]
  node_remoteapp["Remote app commands<br/>[app.rs]"]
  node_remoteconn["Remote connection<br/>[conn.rs]"]
  node_tunnel["Authenticated tunnel<br/>[server.rs]"]
end

node_user(("Developer"))
node_process(("Running program"))
node_cargo["Cargo package"]

node_user -->|"runs or tests"| node_runner
node_cargo -->|"provides package"| node_runner
node_runner -.->|"loads source"| node_program
node_program -->|"uses parsed files"| node_parser
node_program -->|"collects definitions"| node_definitions
node_program -->|"expands macros"| node_macros
node_program -->|"resolves builtins"| node_builtins
node_runner -->|"checks package"| node_checker
node_runner -.->|"starts runtime"| node_run
node_run -->|"compiles on demand"| node_jit
node_serve -->|"dispatches compilation"| node_jit
node_serve -->|"dispatches reload"| node_reload
node_serve -->|"dispatches execution"| node_run
node_user -->|"edits source"| node_reload
node_reload -->|"patches running code"| node_process
node_process -->|"answers inspection"| node_serve
node_inspectclient -->|"sends requests"| node_serve
node_inspectclient -->|"routes remote commands"| node_remoteapp
node_remoteapp -->|"uses connection"| node_remoteconn
node_remoteconn -.->|"communicates over tunnel"| node_tunnel
node_instrument -.->|"samples runtime"| node_process
node_threads -.->|"inspects threads"| node_process
node_timeline -.->|"reports events"| node_process
node_heap -.->|"tracks allocations"| node_process
node_profmodel -->|"formats findings"| node_inspectclient
node_user -->|"requests diagnostics"| node_inspectclient

click node_runner "https://github.com/makepad/relax/blob/main/tools/run/runner/src/lib.rs"
click node_program "https://github.com/makepad/relax/blob/main/libs/relax/front/src/program.rs"
click node_parser "https://github.com/makepad/relax/blob/main/libs/relax/front/src/parser.rs"
click node_definitions "https://github.com/makepad/relax/blob/main/libs/relax/front/src/def_collector.rs"
click node_macros "https://github.com/makepad/relax/blob/main/libs/relax/front/src/macros.rs"
click node_builtins "https://github.com/makepad/relax/blob/main/libs/relax/front/src/builtins.rs"
click node_checker "https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/check.rs"
click node_domain "https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/domain.rs"
click node_jit "https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/jit.rs"
click node_run "https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/run.rs"
click node_serve "https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/serve.rs"
click node_reload "https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/reload.rs"
click node_owner "https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/owner.rs"
click node_instrument "https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/inspect/instrument.rs"
click node_threads "https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/inspect/threads.rs"
click node_timeline "https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/inspect/timeline.rs"
click node_heap "https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/inspect/heap.rs"
click node_profmodel "https://github.com/makepad/relax/blob/main/libs/prof_stream/src/model.rs"
click node_inspectclient "https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/inspect/client.rs"
click node_remoteapp "https://github.com/makepad/relax/blob/main/libs/remote/src/app.rs"
click node_remoteconn "https://github.com/makepad/relax/blob/main/libs/remote/src/conn.rs"
click node_tunnel "https://github.com/makepad/relax/blob/main/libs/remote/src/server.rs"

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_runner,node_domain,node_jit,node_run toneBlue
class node_program,node_parser,node_definitions,node_macros,node_builtins,node_checker toneAmber
class node_serve,node_reload,node_owner toneMint
class node_instrument,node_threads,node_timeline,node_heap,node_profmodel,node_inspectclient toneRose
class node_remoteapp,node_remoteconn,node_tunnel,node_user,node_process,node_cargo toneIndigo
```

## Components

### Run and compile

- [Runner CLI](https://github.com/makepad/relax/blob/main/tools/run/runner/src/lib.rs): `tools/run/runner/src/lib.rs`
- [Compiler domain](https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/domain.rs): `libs/relax/compiler/src/domain.rs`
- [JIT compilation](https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/jit.rs): `libs/relax/compiler/src/jit.rs`
- [Program runtime](https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/run.rs): `libs/relax/compiler/src/run.rs`

### Rust front end

- [Program model](https://github.com/makepad/relax/blob/main/libs/relax/front/src/program.rs): `libs/relax/front/src/program.rs`
- [Rust parser](https://github.com/makepad/relax/blob/main/libs/relax/front/src/parser.rs): `libs/relax/front/src/parser.rs`
- [Definition collection](https://github.com/makepad/relax/blob/main/libs/relax/front/src/def_collector.rs): `libs/relax/front/src/def_collector.rs`
- [Macro expansion](https://github.com/makepad/relax/blob/main/libs/relax/front/src/macros.rs): `libs/relax/front/src/macros.rs`
- [Language builtins](https://github.com/makepad/relax/blob/main/libs/relax/front/src/builtins.rs): `libs/relax/front/src/builtins.rs`
- [Type checking](https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/check.rs): `libs/relax/compiler/src/check.rs`

### Live process

- [Runtime service](https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/serve.rs): `libs/relax/compiler/src/serve.rs`
- [Live reload](https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/reload.rs): `libs/relax/compiler/src/reload.rs`
- [Code ownership](https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/owner.rs): `libs/relax/compiler/src/owner.rs`

### Inspection

- [Runtime instrumentation](https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/inspect/instrument.rs): `libs/relax/compiler/src/inspect/instrument.rs`
- [Thread inspection](https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/inspect/threads.rs): `libs/relax/compiler/src/inspect/threads.rs`
- [Event timeline](https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/inspect/timeline.rs): `libs/relax/compiler/src/inspect/timeline.rs`
- [Heap inspection](https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/inspect/heap.rs): `libs/relax/compiler/src/inspect/heap.rs`
- [Profile model](https://github.com/makepad/relax/blob/main/libs/prof_stream/src/model.rs): `libs/prof_stream/src/model.rs`
- [Inspect client](https://github.com/makepad/relax/blob/main/libs/relax/compiler/src/inspect/client.rs): `libs/relax/compiler/src/inspect/client.rs`

### Remote access

- [Remote app commands](https://github.com/makepad/relax/blob/main/libs/remote/src/app.rs): `libs/remote/src/app.rs`
- [Remote connection](https://github.com/makepad/relax/blob/main/libs/remote/src/conn.rs): `libs/remote/src/conn.rs`
- [Authenticated tunnel](https://github.com/makepad/relax/blob/main/libs/remote/src/server.rs): `libs/remote/src/server.rs`

### Other components

- **Developer**
- **Running program**
- **Cargo package**

## Connections

- Developer → Runner CLI: runs or tests
- Cargo package → Runner CLI: provides package
- Runner CLI → Program model: loads source
- Program model → Rust parser: uses parsed files (evidence: `libs/relax/front/src/program.rs`)
- Program model → Definition collection: collects definitions (evidence: `libs/relax/front/src/program.rs`)
- Program model → Macro expansion: expands macros (evidence: `libs/relax/front/src/program.rs`)
- Program model → Language builtins: resolves builtins (evidence: `libs/relax/front/src/program.rs`)
- Runner CLI → Type checking: checks package (evidence: `tools/run/runner/src/lib.rs`)
- Runner CLI → Program runtime: starts runtime
- Program runtime → JIT compilation: compiles on demand (evidence: `libs/relax/compiler/src/serve.rs`)
- Runtime service → JIT compilation: dispatches compilation (evidence: `libs/relax/compiler/src/serve.rs`)
- Runtime service → Live reload: dispatches reload (evidence: `libs/relax/compiler/src/serve.rs`)
- Runtime service → Program runtime: dispatches execution (evidence: `libs/relax/compiler/src/serve.rs`)
- Developer → Live reload: edits source
- Live reload → Running program: patches running code
- Running program → Runtime service: answers inspection
- Inspect client → Runtime service: sends requests
- Inspect client → Remote app commands: routes remote commands (evidence: `libs/relax/compiler/src/inspect/client.rs`)
- Remote app commands → Remote connection: uses connection (evidence: `libs/remote/src/app.rs`)
- Remote connection → Authenticated tunnel: communicates over tunnel
- Runtime instrumentation → Running program: samples runtime
- Thread inspection → Running program: inspects threads
- Event timeline → Running program: reports events
- Heap inspection → Running program: tracks allocations
- Profile model → Inspect client: formats findings
- Developer → Inspect client: requests diagnostics
