# alan-d-mitchell/vypr architecture

> Architecture diagram of the GitHub repository alan-d-mitchell/vypr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alan-d-mitchell/vypr
- Repository: https://github.com/alan-d-mitchell/vypr

## Overview

Vypr is organized as a Rust workspace with one executable crate and several library crates that form a source-to-VM pipeline.

1. **Entry point: `cli`**
   - `cli/src/main.rs` is the user-facing command line binary.
   - It likely reads a `.vypr` source file, invokes the compiler pipeline, and runs the program on the VM.

2. **Shared error model: `crates/error`**
   - This is a common dependency used across the workspace for diagnostics and failure handling.
   - It provides the repository-wide error type so lexer, parser, semantic analysis, IR builders, and VM can report issues consistently.

3. **Front end: `crates/lexer`**
   - Converts Vypr source text into tokens.
   - The presence of `token.rs` and `lexer.rs` indicates a standalone lexical stage before parsing.

4. **Syntax layer: `crates/parser`**
   - Turns tokens into an AST (`ast.rs`).
   - This is the language’s structural model for statements, expressions, literals, function definitions, and other Python-like constructs.

5. **Semantic analysis: `crates/semantic`**
   - Responsible for scope handling, method resolution, and type-related checks.
   - `scope.rs` and `methods.rs` show that this crate manages lexical scoping, symbol resolution, and the rules behind gradual typing.
   - This is where annotated variables are distinguished from dynamic ones, and where many static errors are detected before execution.

6. **First IR layer: `crates/vir`**
   - Vypr has an intermediate representation called VIR.
   - `builder.rs` suggests AST-to-VIR lowering, while `context.rs` likely carries symbol/type state across lowering passes.
   - This layer is an architectural boundary between language semantics and VM-oriented representation.

7. **Second IR layer: `crates/mir`**
   - MIR is a lower-level intermediate form than VIR.
   - `builder.rs` and `display.rs` indicate another lowering pass plus debugging/inspection support.
   - The two-stage IR design suggests the compiler separates high-level language structure from execution-friendly operations.

8. **Runtime backend: `crates/vm`**
   - This is the execution engine: a custom stack-based virtual machine.
   - `bytecode.rs`, `compiler.rs`, and `vm.rs` show the path from lowered IR into executable bytecode and then into runtime interpretation.
   - `value.rs` likely defines the VM’s runtime value model, including typed and dynamic values.

9. **Built-ins and standard library: `crates/vm/src/stdlib`**
   - Vypr includes native modules for `math`, `time`, `os`, and `canvas`.
   - `builtins.rs` and `methods.rs` indicate intrinsic functions and type-specific methods are implemented inside the VM/runtime boundary, not in userland code.
   - This is the main external-facing runtime extension surface.

10. **Bytecode persistence/support: `serializer.rs`**
   - The VM includes serialization support for bytecode or compiled artifacts.
   - That implies the runtime can likely persist or reload compiled forms, even if the primary workflow is direct compile-and-run.

11. **End-to-end data flow**
   - Source file → lexer tokens → parser AST → semantic analysis → VIR → MIR → VM bytecode → stack-based execution.
   - Type enforcement is split across compile-time semantic checks and runtime enforcement for annotated values, matching the gradual typing model described in the README.

12. **Repository boundary and examples**
   - The `examples/` directory is not part of the runtime, but it is important for understanding intended language behavior.
   - The sample programs cover gradual typing, coercion, data pipelines, fractals, and error cases, which makes them useful reference points for the language features exercised by the compiler and VM.

13. **Diagramming implication**
   - The cleanest architecture diagram is a left-to-right compiler pipeline feeding a runtime box.
   - Keep the compiler frontend, IR lowering stages, and VM/runtime as separate layers, with `error` and `stdlib` shown as cross-cutting support components.

Main entry points: [`crates/vm/src/vm.rs`](https://github.com/alan-d-mitchell/vypr/blob/master/crates/vm/src/vm.rs) (VM), [`crates/error/src/lib.rs`](https://github.com/alan-d-mitchell/vypr/blob/master/crates/error/src/lib.rs) (Errors), [`crates/semantic/src/analyzer.rs`](https://github.com/alan-d-mitchell/vypr/blob/master/crates/semantic/src/analyzer.rs) (Analyzer), [`crates/lexer/src/lexer.rs`](https://github.com/alan-d-mitchell/vypr/blob/master/crates/lexer/src/lexer.rs) (Lexer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Tooling"]
  node_n1["CLI<br/>binary<br/>[main.rs]"]
end

subgraph group_g2["Front end"]
  node_n3["Lexer<br/>tokenizer<br/>[lexer.rs]"]
  node_n4["Tokens<br/>token model<br/>[token.rs]"]
  node_n5["Parser<br/>[parser.rs]"]
  node_n6["AST<br/>syntax tree<br/>[ast.rs]"]
  node_n7["Analyzer<br/>semantic analysis<br/>[analyzer.rs]"]
  node_n8["Scope<br/>symbol table<br/>[scope.rs]"]
  node_n9["Methods<br/>resolution rules<br/>[methods.rs]"]
end

subgraph group_g3["IR"]
  node_n10["VIR Builder<br/>lowering pass<br/>[builder.rs]"]
  node_n11["VIR<br/>mid-level IR<br/>[vir.rs]"]
  node_n12["MIR Builder<br/>lowering pass<br/>[builder.rs]"]
  node_n13["MIR<br/>low-level IR<br/>[mir.rs]"]
end

subgraph group_g4["Runtime"]
  node_n14["Compiler<br/>[compiler.rs]"]
  node_n15["Bytecode<br/>instruction set<br/>[bytecode.rs]"]
  node_n16["VM<br/>[vm.rs]"]
  node_n17["Value<br/>runtime model<br/>[value.rs]"]
  node_n18["Stdlib<br/>native modules<br/>[mod.rs]"]
  node_n19["Builtins<br/>intrinsics<br/>[builtins.rs]"]
  node_n20["Serializer<br/>artifact support<br/>[serializer.rs]"]
end

subgraph group_g5["Support"]
  node_n2["Errors<br/>shared crate<br/>[lib.rs]"]
  node_n21["Examples<br/>sample programs"]
end

node_n1 -->|"starts with"| node_n3
node_n3 -->|"produces"| node_n4
node_n4 -->|"consumed by"| node_n5
node_n5 -->|"produces"| node_n6
node_n6 -->|"analyzed by"| node_n7
node_n7 -->|"uses"| node_n8
node_n7 -->|"uses"| node_n9
node_n7 -->|"lowers to"| node_n10
node_n10 -->|"produces"| node_n11
node_n11 -->|"lowers to"| node_n12
node_n12 -->|"produces"| node_n13
node_n13 -->|"feeds"| node_n14
node_n14 -->|"produces"| node_n15
node_n15 -->|"runs on"| node_n16
node_n16 -->|"manages"| node_n17
node_n16 -->|"loads"| node_n18
node_n16 -->|"exposes"| node_n19
node_n16 -.->|"supports"| node_n20
node_n2 -.->|"shared by"| node_n3
node_n2 -.->|"shared by"| node_n5
node_n2 -.->|"shared by"| node_n7
node_n2 -.->|"shared by"| node_n14
node_n2 -.->|"shared by"| node_n16
node_n21 -.->|"exercises"| node_n1

click node_n1 "https://github.com/alan-d-mitchell/vypr/blob/master/cli/src/main.rs"
click node_n2 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/error/src/lib.rs"
click node_n3 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/lexer/src/lexer.rs"
click node_n4 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/lexer/src/token.rs"
click node_n5 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/parser/src/parser.rs"
click node_n6 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/parser/src/ast.rs"
click node_n7 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/semantic/src/analyzer.rs"
click node_n8 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/semantic/src/scope.rs"
click node_n9 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/semantic/src/methods.rs"
click node_n10 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/vir/src/builder.rs"
click node_n11 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/vir/src/vir.rs"
click node_n12 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/mir/src/builder.rs"
click node_n13 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/mir/src/mir.rs"
click node_n14 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/vm/src/compiler.rs"
click node_n15 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/vm/src/bytecode.rs"
click node_n16 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/vm/src/vm.rs"
click node_n17 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/vm/src/value.rs"
click node_n18 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/vm/src/stdlib/mod.rs"
click node_n19 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/vm/src/builtins.rs"
click node_n20 "https://github.com/alan-d-mitchell/vypr/blob/master/crates/vm/src/serializer.rs"
click node_n21 "https://github.com/alan-d-mitchell/vypr/blob/master/examples/01_gradual_typing.vypr"

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_n1 toneBlue
class node_n3,node_n4,node_n5,node_n6,node_n7,node_n8,node_n9 toneAmber
class node_n10,node_n11,node_n12,node_n13 toneMint
class node_n14,node_n15,node_n16,node_n17,node_n18,node_n19,node_n20 toneRose
class node_n2,node_n21 toneIndigo
```

## Components

### Tooling

Workspace entrypoint and user-facing command line

- [CLI](https://github.com/alan-d-mitchell/vypr/blob/master/cli/src/main.rs): binary · Command-line entrypoint that drives the compile-and-run flow · `cli/src/main.rs`

### Front end

Source parsing and semantic checks

- [Lexer](https://github.com/alan-d-mitchell/vypr/blob/master/crates/lexer/src/lexer.rs): tokenizer · Converts source text into tokens · `crates/lexer/src/lexer.rs`
- [Tokens](https://github.com/alan-d-mitchell/vypr/blob/master/crates/lexer/src/token.rs): token model · Lexical token definitions used by the parser · `crates/lexer/src/token.rs`
- [Parser](https://github.com/alan-d-mitchell/vypr/blob/master/crates/parser/src/parser.rs): syntax parser · Builds the AST from token streams · `crates/parser/src/parser.rs`
- [AST](https://github.com/alan-d-mitchell/vypr/blob/master/crates/parser/src/ast.rs): syntax tree · Language structure for statements, expressions, and definitions · `crates/parser/src/ast.rs`
- [Analyzer](https://github.com/alan-d-mitchell/vypr/blob/master/crates/semantic/src/analyzer.rs): semantic analysis · Performs scope and type-related validation · `crates/semantic/src/analyzer.rs`
- [Scope](https://github.com/alan-d-mitchell/vypr/blob/master/crates/semantic/src/scope.rs): symbol table · Tracks lexical scopes and bindings during analysis · `crates/semantic/src/scope.rs`
- [Methods](https://github.com/alan-d-mitchell/vypr/blob/master/crates/semantic/src/methods.rs): resolution rules · Handles method lookup and related semantic rules · `crates/semantic/src/methods.rs`

### IR

Intermediate representations between language and runtime

- [VIR Builder](https://github.com/alan-d-mitchell/vypr/blob/master/crates/vir/src/builder.rs): lowering pass · Lowers analyzed AST into the higher-level intermediate form · `crates/vir/src/builder.rs`
- [VIR](https://github.com/alan-d-mitchell/vypr/blob/master/crates/vir/src/vir.rs): mid-level IR · Higher-level intermediate representation used between semantics and codegen · `crates/vir/src/vir.rs`
- [MIR Builder](https://github.com/alan-d-mitchell/vypr/blob/master/crates/mir/src/builder.rs): lowering pass · Lowers VIR into the lower-level intermediate form · `crates/mir/src/builder.rs`
- [MIR](https://github.com/alan-d-mitchell/vypr/blob/master/crates/mir/src/mir.rs): low-level IR · Execution-oriented intermediate representation · `crates/mir/src/mir.rs`

### Runtime

Virtual machine, bytecode, and built-in modules

- [Compiler](https://github.com/alan-d-mitchell/vypr/blob/master/crates/vm/src/compiler.rs): bytecode compiler · Converts lowered IR into VM bytecode · `crates/vm/src/compiler.rs`
- [Bytecode](https://github.com/alan-d-mitchell/vypr/blob/master/crates/vm/src/bytecode.rs): instruction set · Executable form consumed by the virtual machine · `crates/vm/src/bytecode.rs`
- [VM](https://github.com/alan-d-mitchell/vypr/blob/master/crates/vm/src/vm.rs): stack VM · Runtime execution engine for compiled programs · `crates/vm/src/vm.rs`
- [Value](https://github.com/alan-d-mitchell/vypr/blob/master/crates/vm/src/value.rs): runtime model · Represents runtime values and typed data · `crates/vm/src/value.rs`
- [Stdlib](https://github.com/alan-d-mitchell/vypr/blob/master/crates/vm/src/stdlib/mod.rs): native modules · Built-in modules and intrinsic runtime functions · `crates/vm/src/stdlib/mod.rs`
- [Builtins](https://github.com/alan-d-mitchell/vypr/blob/master/crates/vm/src/builtins.rs): intrinsics · Core built-in functions exposed by the runtime · `crates/vm/src/builtins.rs`
- [Serializer](https://github.com/alan-d-mitchell/vypr/blob/master/crates/vm/src/serializer.rs): artifact support · Persists or reloads compiled bytecode artifacts · `crates/vm/src/serializer.rs`

### Support

Cross-cutting error handling and examples

- [Errors](https://github.com/alan-d-mitchell/vypr/blob/master/crates/error/src/lib.rs): shared crate · Repository-wide diagnostic and failure model · `crates/error/src/lib.rs`
- [Examples](https://github.com/alan-d-mitchell/vypr/blob/master/examples/01_gradual_typing.vypr): sample programs · Reference programs showing language behavior and error cases · `examples/01_gradual_typing.vypr`

## Connections

- CLI → Lexer: starts with · CLI feeds source text into lexical analysis
- Lexer → Tokens: produces · Lexer emits token streams using token definitions
- Tokens → Parser: consumed by · Parser reads tokens to build syntax
- Parser → AST: produces · Parser outputs the AST
- AST → Analyzer: analyzed by · AST is validated for scope and semantic rules
- Analyzer → Scope: uses · Analyzer depends on scope tracking
- Analyzer → Methods: uses · Analyzer relies on method resolution rules
- Analyzer → VIR Builder: lowers to · Validated program is lowered into VIR
- VIR Builder → VIR: produces · Builder emits the higher-level IR
- VIR → MIR Builder: lowers to · VIR is transformed into MIR
- MIR Builder → MIR: produces · Builder emits the lower-level IR
- MIR → Compiler: feeds · MIR is compiled into bytecode
- Compiler → Bytecode: produces · Compiler outputs executable bytecode
- Bytecode → VM: runs on · Bytecode is interpreted by the VM
- VM → Value: manages · VM evaluates and stores runtime values
- VM → Stdlib: loads · VM exposes native standard library modules
- VM → Builtins: exposes · Runtime provides built-in functions and methods
- VM → Serializer: supports · VM can serialize compiled artifacts
- Errors → Lexer: shared by · Lexing reports failures through the common error model
- Errors → Parser: shared by · Parsing reports failures through the common error model
- Errors → Analyzer: shared by · Semantic analysis reports failures through the common error model
- Errors → Compiler: shared by · Compilation reports failures through the common error model
- Errors → VM: shared by · Runtime errors use the common error model
- Examples → CLI: exercises · Examples demonstrate the end-to-end toolchain