# dilanr/rustpiler architecture

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

- Interactive diagram: https://gitdiagram.com/dilanr/rustpiler
- Repository: https://github.com/dilanr/rustpiler

## Overview

RnR is a small language toolchain with a CLI and browser playground. The main workflow accepts source, parses it into an AST, type-checks it, then optionally interprets it or generates and runs MIPS-like code. The playground adds in-browser compilation, diagnostics, editing, and AST exploration. The pipeline and CLI behavior are documented; the WASM adapter and CLI internals were not sampled, so their detailed wiring is omitted.

Main entry points: [`crates/cli/src/cli.rs`](https://github.com/dilanr/rustpiler/blob/main/crates/cli/src/cli.rs) (CLI options), [`crates/compiler/src/pipeline.rs`](https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/pipeline.rs) (Compiler pipeline), [`playground/src/workspace/hooks/useWorkspace.tsx`](https://github.com/dilanr/rustpiler/blob/main/playground/src/workspace/hooks/useWorkspace.tsx) (Playground workspace), [`playground/src/features/compiler/hooks/useRustpiler.ts`](https://github.com/dilanr/rustpiler/blob/main/playground/src/features/compiler/hooks/useRustpiler.ts) (Browser compiler hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_cli_app["CLI app<br/>[main.rs]"]
  node_cli_options["CLI options<br/>[cli.rs]"]
end

subgraph group_compiler["Compiler"]
  node_pipeline["Compiler pipeline<br/>[pipeline.rs]"]
  node_parser["Parser<br/>[parse.rs]"]
  node_ast["Program AST<br/>[mod.rs]"]
  node_type_checker["Type checker<br/>[type_check.rs]"]
  node_diagnostics["Diagnostics<br/>[diagnostic.rs]"]
  node_ast_format["AST serialization<br/>[serialize.rs]"]
end

subgraph group_execution["Execution"]
  node_interpreter["Tree-walk VM<br/>[vm.rs]"]
  node_codegen["MIPS codegen<br/>[code_gen.rs]"]
  node_mips_vm["MIPS VM runner<br/>[pipeline.rs]"]
end

subgraph group_playground["Playground"]
  node_wasm["WASM interface<br/>[lib.rs]"]
  node_playground["Playground workspace<br/>[useWorkspace.tsx]"]
  node_play_compiler["Browser compiler hook<br/>[useRustpiler.ts]"]
  node_editor["Code editor<br/>[CodeEditor.tsx]"]
  node_markers["Editor diagnostics"]
  node_ast_view["AST visualization<br/>[AstGraph.tsx]"]
  node_console["Run output<br/>[Console.tsx]"]
end

node_user(("Language user"))
node_source["RnR source"]
node_assembly_file["Assembly file"]
node_ast_file["AST dump file"]

node_user -->|"invokes"| node_cli_app
node_cli_app -->|"parses options"| node_cli_options
node_cli_options -->|"reads input"| node_source
node_cli_options -->|"selects stages"| node_pipeline
node_pipeline -->|"parses source"| node_parser
node_parser -->|"produces AST"| node_ast
node_pipeline -->|"checks program"| node_type_checker
node_type_checker -->|"reports errors"| node_diagnostics
node_cli_options -->|"requests AST dump"| node_ast_format
node_cli_options -->|"writes dump"| node_ast_file
node_cli_options -->|"runs interpreter"| node_interpreter
node_pipeline -->|"evaluates program"| node_interpreter
node_cli_options -->|"requests codegen"| node_codegen
node_pipeline -->|"generates instructions"| node_codegen
node_pipeline -->|"runs instructions"| node_mips_vm
node_cli_options -->|"writes assembly"| node_assembly_file
node_user -->|"edits and runs"| node_playground
node_playground -->|"hosts editor"| node_editor
node_playground -->|"runs compilation"| node_play_compiler
node_play_compiler -->|"calls compile"| node_wasm
node_play_compiler -->|"provides diagnostics"| node_markers
node_playground -->|"shows AST"| node_ast_view
node_playground -->|"shows results"| node_console
node_wasm -.->|"compiles source"| node_pipeline

click node_cli_app "https://github.com/dilanr/rustpiler/blob/main/crates/cli/src/main.rs"
click node_cli_options "https://github.com/dilanr/rustpiler/blob/main/crates/cli/src/cli.rs"
click node_pipeline "https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/pipeline.rs"
click node_parser "https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/parse.rs"
click node_ast "https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/ast/mod.rs"
click node_type_checker "https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/type_check.rs"
click node_diagnostics "https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/error/diagnostic.rs"
click node_ast_format "https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/ast/serialize.rs"
click node_interpreter "https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/vm.rs"
click node_codegen "https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/code_gen.rs"
click node_mips_vm "https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/pipeline.rs"
click node_wasm "https://github.com/dilanr/rustpiler/blob/main/crates/wasm/src/lib.rs"
click node_playground "https://github.com/dilanr/rustpiler/blob/main/playground/src/workspace/hooks/useWorkspace.tsx"
click node_play_compiler "https://github.com/dilanr/rustpiler/blob/main/playground/src/features/compiler/hooks/useRustpiler.ts"
click node_editor "https://github.com/dilanr/rustpiler/blob/main/playground/src/features/editor/components/CodeEditor.tsx"
click node_markers "https://github.com/dilanr/rustpiler/blob/main/playground/src/features/editor/hooks/useMonacoMarkers.ts"
click node_ast_view "https://github.com/dilanr/rustpiler/blob/main/playground/src/features/ast/components/AstGraph.tsx"
click node_console "https://github.com/dilanr/rustpiler/blob/main/playground/src/workspace/components/Console.tsx"

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_app,node_cli_options,node_user toneBlue
class node_pipeline,node_parser,node_ast,node_type_checker,node_diagnostics,node_ast_format toneAmber
class node_interpreter,node_codegen,node_mips_vm toneMint
class node_wasm,node_playground,node_play_compiler,node_editor,node_markers,node_ast_view,node_console toneRose
class node_source,node_assembly_file,node_ast_file toneIndigo
```

## Components

### CLI

- [CLI app](https://github.com/dilanr/rustpiler/blob/main/crates/cli/src/main.rs): `crates/cli/src/main.rs`
- [CLI options](https://github.com/dilanr/rustpiler/blob/main/crates/cli/src/cli.rs): `crates/cli/src/cli.rs`

### Compiler

- [Compiler pipeline](https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/pipeline.rs): `crates/compiler/src/pipeline.rs`
- [Parser](https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/parse.rs): `crates/compiler/src/parse.rs`
- [Program AST](https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/ast/mod.rs): `crates/compiler/src/ast/mod.rs`
- [Type checker](https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/type_check.rs): `crates/compiler/src/type_check.rs`
- [Diagnostics](https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/error/diagnostic.rs): `crates/compiler/src/error/diagnostic.rs`
- [AST serialization](https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/ast/serialize.rs): `crates/compiler/src/ast/serialize.rs`

### Execution

- [Tree-walk VM](https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/vm.rs): `crates/compiler/src/vm.rs`
- [MIPS codegen](https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/code_gen.rs): `crates/compiler/src/code_gen.rs`
- [MIPS VM runner](https://github.com/dilanr/rustpiler/blob/main/crates/compiler/src/pipeline.rs): `crates/compiler/src/pipeline.rs`

### Playground

- [WASM interface](https://github.com/dilanr/rustpiler/blob/main/crates/wasm/src/lib.rs): `crates/wasm/src/lib.rs`
- [Playground workspace](https://github.com/dilanr/rustpiler/blob/main/playground/src/workspace/hooks/useWorkspace.tsx): `playground/src/workspace/hooks/useWorkspace.tsx`
- [Browser compiler hook](https://github.com/dilanr/rustpiler/blob/main/playground/src/features/compiler/hooks/useRustpiler.ts): `playground/src/features/compiler/hooks/useRustpiler.ts`
- [Code editor](https://github.com/dilanr/rustpiler/blob/main/playground/src/features/editor/components/CodeEditor.tsx): `playground/src/features/editor/components/CodeEditor.tsx`
- [Editor diagnostics](https://github.com/dilanr/rustpiler/blob/main/playground/src/features/editor/hooks/useMonacoMarkers.ts): `playground/src/features/editor/hooks/useMonacoMarkers.ts`
- [AST visualization](https://github.com/dilanr/rustpiler/blob/main/playground/src/features/ast/components/AstGraph.tsx): `playground/src/features/ast/components/AstGraph.tsx`
- [Run output](https://github.com/dilanr/rustpiler/blob/main/playground/src/workspace/components/Console.tsx): `playground/src/workspace/components/Console.tsx`

### Other components

- **Language user**
- **RnR source**
- **Assembly file**
- **AST dump file**

## Connections

- Language user → CLI app: invokes
- CLI app → CLI options: parses options
- CLI options → RnR source: reads input
- CLI options → Compiler pipeline: selects stages
- Compiler pipeline → Parser: parses source
- Parser → Program AST: produces AST
- Compiler pipeline → Type checker: checks program
- Type checker → Diagnostics: reports errors
- CLI options → AST serialization: requests AST dump
- CLI options → AST dump file: writes dump
- CLI options → Tree-walk VM: runs interpreter
- Compiler pipeline → Tree-walk VM: evaluates program
- CLI options → MIPS codegen: requests codegen
- Compiler pipeline → MIPS codegen: generates instructions
- Compiler pipeline → MIPS VM runner: runs instructions
- CLI options → Assembly file: writes assembly
- Language user → Playground workspace: edits and runs
- Playground workspace → Code editor: hosts editor
- Playground workspace → Browser compiler hook: runs compilation
- Browser compiler hook → WASM interface: calls compile
- Browser compiler hook → Editor diagnostics: provides diagnostics
- Playground workspace → AST visualization: shows AST
- Playground workspace → Run output: shows results
- WASM interface → Compiler pipeline: compiles source