# michaelb3l/ppl2_mikiraz architecture

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

- Interactive diagram: https://gitdiagram.com/michaelb3l/ppl2_mikiraz
- Repository: https://github.com/michaelb3l/ppl2_mikiraz

## Overview

This repository implements an L3 Scheme-like language: source text is parsed into an AST, then evaluated using either an environment-based interpreter or a substitution-based interpreter. The language includes procedures, primitive operations, quoted S-expressions, and classes/objects. The tree and excerpts support both interpreter paths and their shared runtime layers; README content is absent, and the q3 entry point was not excerpted, so its exact orchestration is unclear.

Main entry points: [`L3/L3-ast.ts`](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/L3-ast.ts) (L3 AST Parser), [`L3/L3-eval-sub.ts`](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/L3-eval-sub.ts) (Substitution Evaluator), [`shared/result.ts`](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/shared/result.ts) (Result Handling), [`L3/L3-eval-env.ts`](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/L3-eval-env.ts) (Environment Evaluator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language Front End"]
  node_parser["S-expression Adapter<br/>[parser.ts]"]
  node_ast["L3 AST Parser<br/>[L3-ast.ts]"]
  node_transform["Syntax Transformation"]
end

subgraph group_runtime["Evaluation Runtime"]
  node_env_eval["Environment Evaluator<br/>[L3-eval-env.ts]"]
  node_sub_eval["Substitution Evaluator<br/>[L3-eval-sub.ts]"]
  node_env["Environment Frames<br/>[L3-env-env.ts]"]
  node_sub_env["Substitution Environment<br/>[L3-env-sub.ts]"]
  node_substitute["Expression Substitution<br/>[substitute.ts]"]
  node_values["Runtime Values<br/>[L3-value.ts]"]
  node_primitives["Primitive Operations<br/>[evalPrimitive.ts]"]
end

subgraph group_shared["Shared Utilities"]
  node_result["Result Handling<br/>[result.ts]"]
  node_lists["List Operations<br/>[list.ts]"]
  node_predicates["Type Predicates<br/>[type-predicates.ts]"]
  node_format["Value Formatting<br/>[format.ts]"]
  node_optional["Optional Values<br/>[optional.ts]"]
end

subgraph group_entry["Program Interface"]
  node_q3["q3 Interface<br/>[q3.ts]"]
end

node_user(("Language User"))
node_sexp["S-expression Parser"]

node_user -.->|"provides program"| node_q3
node_q3 -->|"uses syntax"| node_ast
node_q3 -->|"uses results"| node_result
node_parser -->|"parses input"| node_sexp
node_ast -->|"parses expressions"| node_parser
node_ast -->|"builds values"| node_values
node_ast -->|"returns results"| node_result
node_ast -->|"uses lists"| node_lists
node_ast -->|"checks syntax"| node_predicates
node_ast -->|"formats errors"| node_format
node_transform -->|"uses syntax"| node_ast
node_env_eval -->|"evaluates expressions"| node_ast
node_env_eval -->|"looks up bindings"| node_env
node_env_eval -->|"creates closures"| node_values
node_env_eval -->|"applies primitives"| node_primitives
node_env_eval -->|"parses input"| node_parser
node_env_eval -->|"propagates results"| node_result
node_sub_eval -->|"evaluates expressions"| node_ast
node_sub_eval -->|"looks up bindings"| node_sub_env
node_sub_eval -->|"creates objects"| node_values
node_sub_eval -->|"substitutes arguments"| node_substitute
node_sub_eval -->|"applies primitives"| node_primitives
node_sub_eval -->|"parses input"| node_parser
node_sub_eval -->|"propagates results"| node_result
node_env -->|"stores values"| node_values
node_env -->|"stores procedures"| node_ast
node_sub_env -->|"stores values"| node_values
node_primitives -->|"operates on values"| node_values
node_primitives -->|"returns results"| node_result
node_primitives -->|"uses lists"| node_lists
node_primitives -->|"checks types"| node_predicates
node_result -->|"maps lists"| node_lists
node_result -->|"converts values"| node_optional
node_parser -->|"returns parse result"| node_result
node_parser -->|"checks tokens"| node_predicates

click node_q3 "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/q3.ts"
click node_parser "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/shared/parser.ts"
click node_ast "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/L3-ast.ts"
click node_transform "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/SyntacticTransformation.ts"
click node_env_eval "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/L3-eval-env.ts"
click node_sub_eval "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/L3-eval-sub.ts"
click node_env "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/L3-env-env.ts"
click node_sub_env "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/L3-env-sub.ts"
click node_substitute "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/substitute.ts"
click node_values "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/L3-value.ts"
click node_primitives "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/evalPrimitive.ts"
click node_result "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/shared/result.ts"
click node_lists "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/shared/list.ts"
click node_predicates "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/shared/type-predicates.ts"
click node_format "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/shared/format.ts"
click node_optional "https://github.com/michaelb3l/ppl2_mikiraz/blob/master/shared/optional.ts"

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_ast,node_transform,node_user toneBlue
class node_env_eval,node_sub_eval,node_env,node_sub_env,node_substitute,node_values,node_primitives toneAmber
class node_result,node_lists,node_predicates,node_format,node_optional toneMint
class node_q3 toneRose
class node_sexp toneIndigo
```

## Components

### Language Front End

- [S-expression Adapter](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/shared/parser.ts): `shared/parser.ts`
- [L3 AST Parser](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/L3-ast.ts): `L3/L3-ast.ts`
- [Syntax Transformation](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/SyntacticTransformation.ts): `L3/SyntacticTransformation.ts`

### Evaluation Runtime

- [Environment Evaluator](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/L3-eval-env.ts): `L3/L3-eval-env.ts`
- [Substitution Evaluator](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/L3-eval-sub.ts): `L3/L3-eval-sub.ts`
- [Environment Frames](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/L3-env-env.ts): `L3/L3-env-env.ts`
- [Substitution Environment](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/L3-env-sub.ts): `L3/L3-env-sub.ts`
- [Expression Substitution](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/substitute.ts): `L3/substitute.ts`
- [Runtime Values](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/L3-value.ts): `L3/L3-value.ts`
- [Primitive Operations](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/L3/evalPrimitive.ts): `L3/evalPrimitive.ts`

### Shared Utilities

- [Result Handling](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/shared/result.ts): `shared/result.ts`
- [List Operations](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/shared/list.ts): `shared/list.ts`
- [Type Predicates](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/shared/type-predicates.ts): `shared/type-predicates.ts`
- [Value Formatting](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/shared/format.ts): `shared/format.ts`
- [Optional Values](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/shared/optional.ts): `shared/optional.ts`

### Program Interface

- [q3 Interface](https://github.com/michaelb3l/ppl2_mikiraz/blob/master/q3.ts): `q3.ts`

### Other components

- **Language User**
- **S-expression Parser**

## Connections

- Language User → q3 Interface: provides program
- q3 Interface → L3 AST Parser: uses syntax (evidence: `q3.ts`)
- q3 Interface → Result Handling: uses results (evidence: `q3.ts`)
- S-expression Adapter → S-expression Parser: parses input (evidence: `shared/parser.ts`)
- L3 AST Parser → S-expression Adapter: parses expressions (evidence: `L3/L3-ast.ts`)
- L3 AST Parser → Runtime Values: builds values (evidence: `L3/L3-ast.ts`)
- L3 AST Parser → Result Handling: returns results (evidence: `L3/L3-ast.ts`)
- L3 AST Parser → List Operations: uses lists (evidence: `L3/L3-ast.ts`)
- L3 AST Parser → Type Predicates: checks syntax (evidence: `L3/L3-ast.ts`)
- L3 AST Parser → Value Formatting: formats errors (evidence: `L3/L3-ast.ts`)
- Syntax Transformation → L3 AST Parser: uses syntax (evidence: `L3/SyntacticTransformation.ts`)
- Environment Evaluator → L3 AST Parser: evaluates expressions (evidence: `L3/L3-eval-env.ts`)
- Environment Evaluator → Environment Frames: looks up bindings (evidence: `L3/L3-eval-env.ts`)
- Environment Evaluator → Runtime Values: creates closures (evidence: `L3/L3-eval-env.ts`)
- Environment Evaluator → Primitive Operations: applies primitives (evidence: `L3/L3-eval-env.ts`)
- Environment Evaluator → S-expression Adapter: parses input (evidence: `L3/L3-eval-env.ts`)
- Environment Evaluator → Result Handling: propagates results (evidence: `L3/L3-eval-env.ts`)
- Substitution Evaluator → L3 AST Parser: evaluates expressions (evidence: `L3/L3-eval-sub.ts`)
- Substitution Evaluator → Substitution Environment: looks up bindings (evidence: `L3/L3-eval-sub.ts`)
- Substitution Evaluator → Runtime Values: creates objects (evidence: `L3/L3-eval-sub.ts`)
- Substitution Evaluator → Expression Substitution: substitutes arguments (evidence: `L3/L3-eval-sub.ts`)
- Substitution Evaluator → Primitive Operations: applies primitives (evidence: `L3/L3-eval-sub.ts`)
- Substitution Evaluator → S-expression Adapter: parses input (evidence: `L3/L3-eval-sub.ts`)
- Substitution Evaluator → Result Handling: propagates results (evidence: `L3/L3-eval-sub.ts`)
- Environment Frames → Runtime Values: stores values (evidence: `L3/L3-env-env.ts`)
- Environment Frames → L3 AST Parser: stores procedures (evidence: `L3/L3-env-env.ts`)
- Substitution Environment → Runtime Values: stores values (evidence: `L3/L3-env-sub.ts`)
- Primitive Operations → Runtime Values: operates on values (evidence: `L3/evalPrimitive.ts`)
- Primitive Operations → Result Handling: returns results (evidence: `L3/evalPrimitive.ts`)
- Primitive Operations → List Operations: uses lists (evidence: `L3/evalPrimitive.ts`)
- Primitive Operations → Type Predicates: checks types (evidence: `L3/evalPrimitive.ts`)
- Result Handling → List Operations: maps lists (evidence: `shared/result.ts`)
- Result Handling → Optional Values: converts values (evidence: `shared/result.ts`)
- S-expression Adapter → Result Handling: returns parse result (evidence: `shared/parser.ts`)
- S-expression Adapter → Type Predicates: checks tokens (evidence: `shared/parser.ts`)