# ayazxdev/compiler architecture

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

- Interactive diagram: https://gitdiagram.com/ayazxdev/compiler
- Repository: https://github.com/ayazxdev/compiler

## Overview

Luna is a custom scripting language whose source is compiled to Gravity bytecode and run by a quota-limited VM. The main workflow is a script passed to the CLI, which delegates compilation and execution to the VM; a separate sandbox service accepts execution requests and captures output. The README also documents an AST tree-walking interpreter as a differential oracle. The VM excerpt shows its compilation dependencies, but does not expose the complete interpret sequence; arrows below reflect only the orchestration and data flow supported by the available code and documentation.

Main entry points: [`src/vm/VM.cpp`](https://github.com/ayazxdev/compiler/blob/master/src/vm/VM.cpp) (Gravity VM), [`src/parser/Parser.cpp`](https://github.com/ayazxdev/compiler/blob/master/src/parser/Parser.cpp) (Pratt parser), [`src/compiler/Compiler.cpp`](https://github.com/ayazxdev/compiler/blob/master/src/compiler/Compiler.cpp) (Bytecode compiler), [`src/service/SandboxService.cpp`](https://github.com/ayazxdev/compiler/blob/master/src/service/SandboxService.cpp) (Sandbox service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["Luna CLI<br/>[main.cpp]"]
end

subgraph group_language["Luna frontend"]
  node_lexer["Lexer<br/>[Lexer.cpp]"]
  node_tokens["Token definitions<br/>[Token.hpp]"]
  node_parser["Pratt parser<br/>[Parser.cpp]"]
  node_ast["Luna AST<br/>[AST.hpp]"]
  node_arena["AST arena<br/>[Arena.hpp]"]
  node_resolver["Scope resolver<br/>[Resolver.cpp]"]
  node_gravity["Operator precedence<br/>[Gravity.cpp]"]
end

subgraph group_bytecode["Bytecode runtime"]
  node_compiler["Bytecode compiler<br/>[Compiler.cpp]"]
  node_chunk["Bytecode chunk<br/>[Chunk.hpp]"]
  node_opcode["Opcode set<br/>[Opcode.hpp]"]
  node_vm["Gravity VM<br/>[VM.cpp]"]
  node_values["Runtime values<br/>[Value.cpp]"]
end

subgraph group_sandbox["Sandbox service"]
  node_service["Sandbox service<br/>[SandboxService.cpp]"]
end

subgraph group_reference["Reference interpreter"]
  node_treewalker["Tree-walking oracle<br/>[TreeWalker.cpp]"]
end

node_script_user(("Script user"))
node_sandbox_client(("Sandbox client"))

node_script_user -->|"provides script"| node_cli
node_cli -->|"interprets source"| node_vm
node_sandbox_client -->|"submits request"| node_service
node_service -->|"executes code"| node_vm
node_service -->|"returns response"| node_sandbox_client
node_vm -->|"uses frontend"| node_lexer
node_parser -->|"scans tokens"| node_lexer
node_parser -->|"builds nodes"| node_ast
node_parser -->|"allocates nodes"| node_arena
node_parser -->|"uses precedence"| node_gravity
node_lexer -->|"emits tokens"| node_tokens
node_vm -->|"parses source"| node_parser
node_vm -->|"resolves scopes"| node_resolver
node_vm -->|"compiles program"| node_compiler
node_compiler -->|"emits bytecode"| node_chunk
node_compiler -->|"emits instructions"| node_opcode
node_vm -->|"dispatches bytecode"| node_chunk
node_vm -->|"evaluates values"| node_values
node_treewalker -.->|"uses runtime values"| node_values

click node_cli "https://github.com/ayazxdev/compiler/blob/master/src/main.cpp"
click node_service "https://github.com/ayazxdev/compiler/blob/master/src/service/SandboxService.cpp"
click node_lexer "https://github.com/ayazxdev/compiler/blob/master/src/lexer/Lexer.cpp"
click node_tokens "https://github.com/ayazxdev/compiler/blob/master/src/lexer/Token.hpp"
click node_parser "https://github.com/ayazxdev/compiler/blob/master/src/parser/Parser.cpp"
click node_ast "https://github.com/ayazxdev/compiler/blob/master/src/ast/AST.hpp"
click node_arena "https://github.com/ayazxdev/compiler/blob/master/src/memory/Arena.hpp"
click node_resolver "https://github.com/ayazxdev/compiler/blob/master/src/resolver/Resolver.cpp"
click node_gravity "https://github.com/ayazxdev/compiler/blob/master/src/gravity/Gravity.cpp"
click node_compiler "https://github.com/ayazxdev/compiler/blob/master/src/compiler/Compiler.cpp"
click node_chunk "https://github.com/ayazxdev/compiler/blob/master/src/compiler/Chunk.hpp"
click node_opcode "https://github.com/ayazxdev/compiler/blob/master/src/compiler/Opcode.hpp"
click node_vm "https://github.com/ayazxdev/compiler/blob/master/src/vm/VM.cpp"
click node_values "https://github.com/ayazxdev/compiler/blob/master/src/vm/Value.cpp"
click node_treewalker "https://github.com/ayazxdev/compiler/blob/master/src/interpreter/TreeWalker.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_script_user,node_sandbox_client toneBlue
class node_lexer,node_tokens,node_parser,node_ast,node_arena,node_resolver,node_gravity toneAmber
class node_compiler,node_chunk,node_opcode,node_vm,node_values toneMint
class node_service toneRose
class node_treewalker toneIndigo
```

## Components

### Entry points

- [Luna CLI](https://github.com/ayazxdev/compiler/blob/master/src/main.cpp): `src/main.cpp`

### Luna frontend

- [Lexer](https://github.com/ayazxdev/compiler/blob/master/src/lexer/Lexer.cpp): `src/lexer/Lexer.cpp`
- [Token definitions](https://github.com/ayazxdev/compiler/blob/master/src/lexer/Token.hpp): `src/lexer/Token.hpp`
- [Pratt parser](https://github.com/ayazxdev/compiler/blob/master/src/parser/Parser.cpp): `src/parser/Parser.cpp`
- [Luna AST](https://github.com/ayazxdev/compiler/blob/master/src/ast/AST.hpp): `src/ast/AST.hpp`
- [AST arena](https://github.com/ayazxdev/compiler/blob/master/src/memory/Arena.hpp): `src/memory/Arena.hpp`
- [Scope resolver](https://github.com/ayazxdev/compiler/blob/master/src/resolver/Resolver.cpp): `src/resolver/Resolver.cpp`
- [Operator precedence](https://github.com/ayazxdev/compiler/blob/master/src/gravity/Gravity.cpp): `src/gravity/Gravity.cpp`

### Bytecode runtime

- [Bytecode compiler](https://github.com/ayazxdev/compiler/blob/master/src/compiler/Compiler.cpp): `src/compiler/Compiler.cpp`
- [Bytecode chunk](https://github.com/ayazxdev/compiler/blob/master/src/compiler/Chunk.hpp): `src/compiler/Chunk.hpp`
- [Opcode set](https://github.com/ayazxdev/compiler/blob/master/src/compiler/Opcode.hpp): `src/compiler/Opcode.hpp`
- [Gravity VM](https://github.com/ayazxdev/compiler/blob/master/src/vm/VM.cpp): `src/vm/VM.cpp`
- [Runtime values](https://github.com/ayazxdev/compiler/blob/master/src/vm/Value.cpp): `src/vm/Value.cpp`

### Sandbox service

- [Sandbox service](https://github.com/ayazxdev/compiler/blob/master/src/service/SandboxService.cpp): `src/service/SandboxService.cpp`

### Reference interpreter

- [Tree-walking oracle](https://github.com/ayazxdev/compiler/blob/master/src/interpreter/TreeWalker.cpp): `src/interpreter/TreeWalker.cpp`

### Other components

- **Script user**
- **Sandbox client**

## Connections

- Script user → Luna CLI: provides script
- Luna CLI → Gravity VM: interprets source
- Sandbox client → Sandbox service: submits request
- Sandbox service → Gravity VM: executes code
- Sandbox service → Sandbox client: returns response
- Gravity VM → Lexer: uses frontend
- Pratt parser → Lexer: scans tokens
- Pratt parser → Luna AST: builds nodes
- Pratt parser → AST arena: allocates nodes
- Pratt parser → Operator precedence: uses precedence
- Lexer → Token definitions: emits tokens
- Gravity VM → Pratt parser: parses source
- Gravity VM → Scope resolver: resolves scopes
- Gravity VM → Bytecode compiler: compiles program
- Bytecode compiler → Bytecode chunk: emits bytecode
- Bytecode compiler → Opcode set: emits instructions
- Gravity VM → Bytecode chunk: dispatches bytecode
- Gravity VM → Runtime values: evaluates values
- Tree-walking oracle → Runtime values: uses runtime values