# masak/ipso architecture

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

- Interactive diagram: https://gitdiagram.com/masak/ipso
- Repository: https://github.com/masak/ipso

## Overview

##### Core Components and Pipeline
a. Tokenization (tokenize.ts)
b. Parsing (parse-expr.ts, parse-value.ts)
c. Evaluation (evaluate.ts)
d. Compilation (compile.ts)

##### Key Architectural Elements

a. Environment Management:
- Relationship between env.ts and std-env.ts
- Global environment handling mentioned in the README's "Surprise 3"
- Scope management system

b. Evaluation Components:
- CEK Machine architecture (mentioned in README)
- Continuation handling (kont.ts, comp-kont.ts)
- State management (state.ts, comp-state.ts)

c. Core Data Structures:
- Expression representation (expr.ts)
- Value system (value.ts, abstract-value.ts)
- Primitive operations (prims.ts)
- Forms handling (forms.ts)

- Ipso Interpreter                                 |

- ↓

- Input Process |    |    Parser    |    | Evaluator   |    |    Compiler     |
- tokenize.ts  | -> | parse-expr.ts| -> | evaluate.ts | -> |   compile.ts    |
- parse-value.ts|    |            |    |                  |

- ↑                    ↑                    ↑

- Core Types      |  |Environment|    | Runtime Support  |
- expr.ts        |  |  env.ts   |    |   state.ts      |
- value.ts       |  | std-env.ts|    |   kont.ts       |
- forms.ts       |  |           |    |   comp-state.ts  |

##### Additional Notes

- Showing the complete pipeline from input to execution
- Highlighting the unique aspects of this implementation (CEK machine, environment handling)
- Demonstrating the relationship between components
- Illustrating the special cases and surprises mentioned in the README

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Legend
        L1[Processing Component]:::processing
        L2[Data Structure]:::data
        L3[Environment Component]:::env
        L4[Runtime Support]:::runtime
        L5[Utility Component]:::utility
    end

    subgraph "Input Processing"
        Tokenizer["Tokenizer"]:::processing
        click Tokenizer "https://github.com/masak/ipso/blob/master/src/tokenize.ts"
    end

    subgraph "Parser Layer"
        ExprParser["Expression Parser"]:::processing
        ValueParser["Value Parser"]:::processing
        click ExprParser "https://github.com/masak/ipso/blob/master/src/parse-expr.ts"
        click ValueParser "https://github.com/masak/ipso/blob/master/src/parse-value.ts"
    end

    subgraph "Core Data Structures"
        Expr["Expression Types"]:::data
        Value["Value System"]:::data
        AbstractValue["Abstract Values"]:::data
        Forms["Forms Handler"]:::data
        Prims["Primitive Operations"]:::data
        Instr["Instructions"]:::data
        click Expr "https://github.com/masak/ipso/blob/master/src/expr.ts"
        click Value "https://github.com/masak/ipso/blob/master/src/value.ts"
        click AbstractValue "https://github.com/masak/ipso/blob/master/src/abstract-value.ts"
        click Forms "https://github.com/masak/ipso/blob/master/src/forms.ts"
        click Prims "https://github.com/masak/ipso/blob/master/src/prims.ts"
        click Instr "https://github.com/masak/ipso/blob/master/src/instr.ts"
    end

    subgraph "Environment System"
        Env["Environment Manager"]:::env
        StdEnv["Standard Environment"]:::env
        click Env "https://github.com/masak/ipso/blob/master/src/env.ts"
        click StdEnv "https://github.com/masak/ipso/blob/master/src/std-env.ts"
    end

    subgraph "Execution Engine"
        Evaluator["Evaluator"]:::processing
        Compiler["Compiler"]:::processing
        Runner["Runtime Executor"]:::processing
        click Evaluator "https://github.com/masak/ipso/blob/master/src/evaluate.ts"
        click Compiler "https://github.com/masak/ipso/blob/master/src/compile.ts"
        click Runner "https://github.com/masak/ipso/blob/master/src/run.ts"
    end

    subgraph "Runtime Support"
        Kont["Continuation Handler"]:::runtime
        CompKont["Compiler Continuation"]:::runtime
        State["State Manager"]:::runtime
        CompState["Compiler State"]:::runtime
        click Kont "https://github.com/masak/ipso/blob/master/src/kont.ts"
        click CompKont "https://github.com/masak/ipso/blob/master/src/comp-kont.ts"
        click State "https://github.com/masak/ipso/blob/master/src/state.ts"
        click CompState "https://github.com/masak/ipso/blob/master/src/comp-state.ts"
    end

    subgraph "Utilities"
        Zip["Zip Utility"]:::utility
        click Zip "https://github.com/masak/ipso/blob/master/src/zip.ts"
    end

    %% Relationships
    Tokenizer --> ExprParser
    Tokenizer --> ValueParser
    ExprParser --> Evaluator
    ValueParser --> Evaluator
    ExprParser -.-> Expr
    ValueParser -.-> Value
    Evaluator --> Compiler
    Compiler --> Runner
    
    Expr --> Forms
    Value --> AbstractValue
    Forms --> Prims
    
    Evaluator -.-> Env
    Env --> StdEnv
    
    Evaluator --> State
    Evaluator --> Kont
    Compiler --> CompState
    Compiler --> CompKont
    
    Runner -.-> Zip

    %% Styles
    classDef processing fill:#a8d1f0,stroke:#333,stroke-width:2px
    classDef data fill:#90EE90,stroke:#333,stroke-width:2px
    classDef env fill:#FFE5B4,stroke:#333,stroke-width:2px
    classDef runtime fill:#FFA07A,stroke:#333,stroke-width:2px
    classDef utility fill:#DDA0DD,stroke:#333,stroke-width:2px
```
