# polybase/polylang architecture

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

- Interactive diagram: https://gitdiagram.com/polybase/polylang
- Repository: https://github.com/polybase/polylang

## Overview

Polylang compiles a TypeScript-like language into Miden assembly, which can then be run with supplied contract state and advice. Its main stages are lexing/parsing, stable-AST conversion and validation, and code generation; JavaScript/WASM bindings and a browser playground expose additional user-facing workflows. The README documents the compile-and-run path. Some implementation links beyond the sampled excerpts are therefore left unverified; dashed edges indicate those limits.

Main entry points: [`src/compiler/mod.rs`](https://github.com/polybase/polylang/blob/main/src/compiler/mod.rs) (Code generation), [`miden-run/src/main.rs`](https://github.com/polybase/polylang/blob/main/miden-run/src/main.rs) (Miden runner), [`parser/src/lib.rs`](https://github.com/polybase/polylang/blob/main/parser/src/lib.rs) (Parser), [`src/stableast.rs`](https://github.com/polybase/polylang/blob/main/src/stableast.rs) (Stable AST)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language frontend"]
  node_parser["Parser<br/>[lib.rs]"]
  node_lexer["Lexer<br/>[lexer.rs]"]
  node_syntax["Syntax AST<br/>[ast.rs]"]
  node_stableast["Stable AST<br/>[stableast.rs]"]
  node_validation["Contract validation<br/>[validation.rs]"]
end

subgraph group_compiler["Miden compiler"]
  node_compiler_api["Compiler API<br/>[lib.rs]"]
  node_codegen["Code generation<br/>[mod.rs]"]
  node_ir["Compiler IR<br/>[ir.rs]"]
  node_encoder["Miden encoder<br/>[encoder.rs]"]
  node_abi["Value ABI<br/>[lib.rs]"]
end

subgraph group_runtime["Execution and proving"]
  node_runner["Miden runner<br/>[main.rs]"]
  node_prover["Proof generation<br/>[lib.rs]"]
  node_prove_route["Prove route<br/>[prove.rs]"]
  node_server["HTTP server<br/>[main.rs]"]
end

subgraph group_interfaces["User interfaces"]
  node_compile_cli["Compile CLI<br/>[main.rs]"]
  node_js_api["JavaScript API<br/>[index.ts]"]
  node_wasm_bindings["WASM bindings<br/>[js.rs]"]
  node_playground["Browser playground<br/>[Playground.tsx]"]
end

node_developer(("Developer"))
node_source["Polylang source"]
node_assembly["Miden assembly"]
node_miden_vm["Miden VM"]
node_execution["Execution result"]

node_developer -->|"writes"| node_source
node_source -->|"parses"| node_parser
node_parser -->|"tokenizes with"| node_lexer
node_parser -->|"produces"| node_syntax
node_syntax -->|"converts to"| node_stableast
node_stableast -->|"validates against"| node_validation
node_developer -->|"runs"| node_compile_cli
node_compile_cli -.->|"invokes"| node_compiler_api
node_compiler_api -->|"delegates to"| node_codegen
node_codegen -.->|"uses"| node_ir
node_codegen -->|"emits instructions"| node_encoder
node_codegen -.->|"uses value types"| node_abi
node_codegen -->|"generates"| node_assembly
node_assembly -->|"pipes to"| node_runner
node_developer -->|"supplies state"| node_runner
node_runner -.->|"executes on"| node_miden_vm
node_runner -->|"returns result"| node_execution
node_developer -->|"calls"| node_js_api
node_js_api -.->|"loads parser module"| node_wasm_bindings
node_wasm_bindings -->|"uses"| node_stableast
node_developer -.->|"uses"| node_playground
node_prove_route -.->|"requests proof"| node_prover
node_server -.->|"routes to"| node_prove_route

click node_parser "https://github.com/polybase/polylang/blob/main/parser/src/lib.rs"
click node_lexer "https://github.com/polybase/polylang/blob/main/parser/src/lexer.rs"
click node_syntax "https://github.com/polybase/polylang/blob/main/parser/src/ast.rs"
click node_stableast "https://github.com/polybase/polylang/blob/main/src/stableast.rs"
click node_validation "https://github.com/polybase/polylang/blob/main/src/validation.rs"
click node_compiler_api "https://github.com/polybase/polylang/blob/main/src/lib.rs"
click node_codegen "https://github.com/polybase/polylang/blob/main/src/compiler/mod.rs"
click node_ir "https://github.com/polybase/polylang/blob/main/src/compiler/ir.rs"
click node_encoder "https://github.com/polybase/polylang/blob/main/src/compiler/encoder.rs"
click node_abi "https://github.com/polybase/polylang/blob/main/abi/src/lib.rs"
click node_compile_cli "https://github.com/polybase/polylang/blob/main/src/bin/compile/main.rs"
click node_js_api "https://github.com/polybase/polylang/blob/main/js/src/index.ts"
click node_wasm_bindings "https://github.com/polybase/polylang/blob/main/src/js.rs"
click node_playground "https://github.com/polybase/polylang/blob/main/site/components/Playground.tsx"
click node_runner "https://github.com/polybase/polylang/blob/main/miden-run/src/main.rs"
click node_prover "https://github.com/polybase/polylang/blob/main/prover/src/lib.rs"
click node_prove_route "https://github.com/polybase/polylang/blob/main/server-routes/src/prove.rs"
click node_server "https://github.com/polybase/polylang/blob/main/server/src/main.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_parser,node_lexer,node_syntax,node_stableast,node_validation toneBlue
class node_compiler_api,node_codegen,node_ir,node_encoder,node_abi toneAmber
class node_runner,node_prover,node_prove_route,node_server toneMint
class node_compile_cli,node_js_api,node_wasm_bindings,node_playground toneRose
class node_developer,node_source,node_assembly,node_miden_vm,node_execution toneIndigo
```

## Components

### Language frontend

- [Parser](https://github.com/polybase/polylang/blob/main/parser/src/lib.rs): `parser/src/lib.rs`
- [Lexer](https://github.com/polybase/polylang/blob/main/parser/src/lexer.rs): `parser/src/lexer.rs`
- [Syntax AST](https://github.com/polybase/polylang/blob/main/parser/src/ast.rs): `parser/src/ast.rs`
- [Stable AST](https://github.com/polybase/polylang/blob/main/src/stableast.rs): `src/stableast.rs`
- [Contract validation](https://github.com/polybase/polylang/blob/main/src/validation.rs): `src/validation.rs`

### Miden compiler

- [Compiler API](https://github.com/polybase/polylang/blob/main/src/lib.rs): `src/lib.rs`
- [Code generation](https://github.com/polybase/polylang/blob/main/src/compiler/mod.rs): `src/compiler/mod.rs`
- [Compiler IR](https://github.com/polybase/polylang/blob/main/src/compiler/ir.rs): `src/compiler/ir.rs`
- [Miden encoder](https://github.com/polybase/polylang/blob/main/src/compiler/encoder.rs): `src/compiler/encoder.rs`
- [Value ABI](https://github.com/polybase/polylang/blob/main/abi/src/lib.rs): `abi/src/lib.rs`

### Execution and proving

- [Miden runner](https://github.com/polybase/polylang/blob/main/miden-run/src/main.rs): `miden-run/src/main.rs`
- [Proof generation](https://github.com/polybase/polylang/blob/main/prover/src/lib.rs): `prover/src/lib.rs`
- [Prove route](https://github.com/polybase/polylang/blob/main/server-routes/src/prove.rs): `server-routes/src/prove.rs`
- [HTTP server](https://github.com/polybase/polylang/blob/main/server/src/main.rs): `server/src/main.rs`

### User interfaces

- [Compile CLI](https://github.com/polybase/polylang/blob/main/src/bin/compile/main.rs): `src/bin/compile/main.rs`
- [JavaScript API](https://github.com/polybase/polylang/blob/main/js/src/index.ts): `js/src/index.ts`
- [WASM bindings](https://github.com/polybase/polylang/blob/main/src/js.rs): `src/js.rs`
- [Browser playground](https://github.com/polybase/polylang/blob/main/site/components/Playground.tsx): `site/components/Playground.tsx`

### Other components

- **Developer**
- **Polylang source**
- **Miden assembly**
- **Miden VM**
- **Execution result**

## Connections

- Developer → Polylang source: writes (evidence: `README.md`)
- Polylang source → Parser: parses (evidence: `parser/src/lib.rs`)
- Parser → Lexer: tokenizes with (evidence: `parser/src/lib.rs`)
- Parser → Syntax AST: produces (evidence: `parser/src/lib.rs`)
- Syntax AST → Stable AST: converts to (evidence: `src/stableast.rs`)
- Stable AST → Contract validation: validates against (evidence: `src/validation.rs`)
- Developer → Compile CLI: runs (evidence: `README.md`)
- Compile CLI → Compiler API: invokes
- Compiler API → Code generation: delegates to (evidence: `src/lib.rs`)
- Code generation → Compiler IR: uses (evidence: `src/compiler/mod.rs`)
- Code generation → Miden encoder: emits instructions (evidence: `src/compiler/mod.rs`)
- Code generation → Value ABI: uses value types
- Code generation → Miden assembly: generates (evidence: `README.md`)
- Miden assembly → Miden runner: pipes to (evidence: `README.md`)
- Developer → Miden runner: supplies state (evidence: `README.md`)
- Miden runner → Miden VM: executes on
- Miden runner → Execution result: returns result (evidence: `README.md`)
- Developer → JavaScript API: calls (evidence: `js/src/index.ts`)
- JavaScript API → WASM bindings: loads parser module
- WASM bindings → Stable AST: uses (evidence: `src/js.rs`)
- Developer → Browser playground: uses
- Prove route → Proof generation: requests proof
- HTTP server → Prove route: routes to
