# ryone9re/picocaml architecture

> Architecture diagram of the GitHub repository ryone9re/picocaml, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ryone9re/picocaml
- Repository: https://github.com/ryone9re/picocaml

## Overview

Based on our analysis of the file structure and README, the picocaml project is a small interpreter (or mini language implementation) for a subset of OCaml. Its purpose is to provide a REPL interface that lets you interactively experiment with a simplified OCaml-like language, featuring key components like parsing, abstract syntax tree (AST) creation, type systems (including inference and polymorphic types), and evaluation.

##### Main Components
- REPL Interface: Represented by the entry point in src/bin/repl.rs. This is the user’s interactive command-line interface.
- Adapter Module: (src/libs/adapter.rs) Likely responsible for bridging input from the REPL to the language processing pipeline.
- Syntax Module: Found in src/libs/syntax (with files like ast.rs and value.rs). This module handles lexical or syntactic analysis and builds the AST.
- Type System Module: Provided in src/libs/type_system (with files for inference, type_environment, type_scheme, types, unification). It’s responsible for type checking and type inference.
- Execution Module: In src/libs/execution (environment.rs, evaluation.rs). This module manages the evaluation of the AST, possibly with support from an environment to hold state.

##### Relationships and Interactions
- The REPL accepts user commands and sends them to the Adapter.
- The Adapter passes the raw input to the Syntax module, where the source code is parsed into an AST.
- The AST is then processed by the Type System module to perform type checking and inference (noting that parts of the HM type inference are not yet implemented).
- After successful type verification, the AST is fed into the Execution module where the evaluation happens—using an Environment to hold variable bindings.
- The result of evaluation is sent back to the REPL for display.

##### Architectural Patterns and Design Principles
- Layered Architecture: The system is clearly segmented into input (REPL), language processing (syntax parsing, AST generation), semantic analysis (type system), and evaluation (execution/environment). This separation of concerns makes each module individually testable and maintainable.
- Modularity: Each major aspect (syntax, type system, evaluation) is encapsulated in its own subdirectory with logically related files.
- Extensibility: With ongoing TODO tasks (like implementing HM type inference), the design anticipates additions to each module without disrupting the overall structure.

##### Relevant Technologies and Libraries
- Rust is the implementation language (evidenced by Cargo.toml and Cargo.lock), so mention that the system leverages Rust’s module system and tooling.
- The REPL and supporting libraries from the Rust ecosystem may be implicitly part of the design (even if not explicitly detailed in the file tree).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface"
        REPL("REPL Interface")
    end

    subgraph "Language Processing"
        Adapter("Adapter Module")
        subgraph "Syntax Module"
            SyntaxMain("Main Syntax File")
            AST("AST Creation")
            Value("Value Handling")
            SyntaxMain --> AST
            SyntaxMain --> Value
        end
    end

    subgraph "Semantic Analysis"
        TS("Type System Module")
        TInference("Type Inference")
        TEnv("Type Environment")
        TScheme("Type Scheme")
        TTypes("Types")
        TUnify("Unification")
        TS --> TInference --> TEnv --> TScheme --> TTypes --> TUnify
    end

    subgraph "Runtime Execution"
        Exec("Execution Module")
        Env("Environment")
        Eval("Evaluation")
        Exec --> Env --> Eval
    end

    REPL --> Adapter
    Adapter --> SyntaxMain
    AST --> TS
    TUnify --> Exec
    Eval --> REPL

    classDef frontend fill:#add8e6,stroke:#0000ff,stroke-width:2px;
    classDef adapter fill:#90ee90,stroke:#008000,stroke-width:2px;
    classDef syntax fill:#ffd700,stroke:#ff8c00,stroke-width:2px;
    classDef types fill:#dda0dd,stroke:#800080,stroke-width:2px;
    classDef execution fill:#ff7f7f,stroke:#ff0000,stroke-width:2px;

    class REPL frontend;
    class Adapter adapter;
    class SyntaxMain,AST,Value syntax;
    class TS,TInference,TEnv,TScheme,TTypes,TUnify types;
    class Exec,Env,Eval execution;

    click REPL "https://github.com/ryone9re/picocaml/blob/main/src/bin/repl.rs"
    click Adapter "https://github.com/ryone9re/picocaml/blob/main/src/libs/adapter.rs"
    click SyntaxMain "https://github.com/ryone9re/picocaml/blob/main/src/libs/syntax.rs"
    click AST "https://github.com/ryone9re/picocaml/blob/main/src/libs/syntax/ast.rs"
    click Value "https://github.com/ryone9re/picocaml/blob/main/src/libs/syntax/value.rs"
    click TS "https://github.com/ryone9re/picocaml/blob/main/src/libs/type_system.rs"
    click TInference "https://github.com/ryone9re/picocaml/blob/main/src/libs/type_system/inference.rs"
    click TEnv "https://github.com/ryone9re/picocaml/blob/main/src/libs/type_system/type_environment.rs"
    click TScheme "https://github.com/ryone9re/picocaml/blob/main/src/libs/type_system/type_scheme.rs"
    click TTypes "https://github.com/ryone9re/picocaml/blob/main/src/libs/type_system/types.rs"
    click TUnify "https://github.com/ryone9re/picocaml/blob/main/src/libs/type_system/unification.rs"
    click Exec "https://github.com/ryone9re/picocaml/blob/main/src/libs/execution.rs"
    click Env "https://github.com/ryone9re/picocaml/blob/main/src/libs/execution/environment.rs"
    click Eval "https://github.com/ryone9re/picocaml/blob/main/src/libs/execution/evaluation.rs"
```
