# hyuraku/monkey architecture

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

- Interactive diagram: https://gitdiagram.com/hyuraku/monkey
- Repository: https://github.com/hyuraku/monkey

## Overview

##### Main system components
- Lexer: Found in the lexer/ directory (lexer.go and tests). This module handles lexical analysis, reading characters to produce tokens.
- Parser & AST: The parser/ and ast/ directories contain the parser and abstract syntax tree definitions respectively. These two are tightly coupled as the parser converts tokens into an AST representing the program structure.
- Evaluator/Interpreter: Located in evaluator/ which implements the interpreter that takes the AST and evaluates expressions.
- Compiler: The compiler/ folder implements the bytecode compiler that translates the AST into bytecode instructions.
- Virtual Machine (VM): Inside the vm/ directory, the bytecode is executed by the virtual machine implementation.
- Object System: The object/ directory defines the runtime objects (such as integers, booleans, arrays, functions, etc.) used by both the evaluator and the VM.
- Code Definitions: The code/ directory encapsulates definitions related to bytecode instructions and the bytecode instruction set.
- REPL: The repl/ directory runs a Read-Eval-Print Loop, acting as the interactive interface to run Monkey code.
- Token: The token/ directory defines tokens which are the output of the lexer.

##### Understand the relationships and interactions
- Input flows from the REPL (or main.go which acts as the entry point) into the Lexer.
- The Lexer tokenizes the input, sending tokens to the Parser.
- The Parser compiles these tokens into an AST based on parsing rules.
- For interpretation: the Evaluator takes the AST and computes results using the object system.
- For compilation: the Compiler translates the AST into bytecode by using code definitions.
- The Virtual Machine executes the compiled bytecode to produce output or compute results.
- All components are orchestrated in main.go, which bootstraps the system by initializing the necessary modules.

##### Architectural patterns and design principles
- Layered Architecture: The project clearly separates concerns by having distinct modules for lexing, parsing (with AST), evaluation, compiling, and executing bytecode.
- Compiler Pipeline: The system follows the stages – Lexer → Parser → AST → Either Evaluator for direct interpretation or Compiler → VM for compiled execution.
- Testing: Each module has its dedicated test files ensuring modular correctness.
- Clear abstractions: For objects, tokens, and bytecode instructions, abstract data types are used to encapsulate behavior and properties.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs
    subgraph "User Input"
        REPL["REPL / Main Entry"]:::ui
    end

    subgraph "Lexical Analysis"
        Lexer["Lexer"]:::analysis
        Token["Token"]:::analysis
    end

    subgraph "Parsing"
        Parser["Parser"]:::analysis
        AST["AST"]:::data
    end

    subgraph "Interpretation Path"
        Evaluator["Evaluator/Interpreter"]:::execution
    end

    subgraph "Compilation Path"
        Compiler["Compiler"]:::execution
        CodeDef["Code Definitions"]:::data
        VM["Virtual Machine"]:::execution
    end

    subgraph "Runtime"
        ObjSys["Object System"]:::data
    end

    %% Connections
    REPL -->|"provides"| Lexer
    Lexer -->|"sends tokens to"| Parser
    Lexer ---|"uses"| Token
    Parser -->|"builds"| AST
    AST -->|"interprets"| Evaluator
    AST -->|"compiles"| Compiler
    Compiler -->|"generates"| CodeDef
    CodeDef -->|"defines"| VM
    Evaluator -->|"utilizes"| ObjSys
    VM -->|"accesses"| ObjSys

    %% Click Events
    click REPL "https://github.com/hyuraku/monkey/blob/main/repl/repl.go"
    click Lexer "https://github.com/hyuraku/monkey/blob/main/lexer/lexer.go"
    click Token "https://github.com/hyuraku/monkey/blob/main/token/token.go"
    click Parser "https://github.com/hyuraku/monkey/blob/main/parser/parser.go"
    click AST "https://github.com/hyuraku/monkey/blob/main/ast/ast.go"
    click Evaluator "https://github.com/hyuraku/monkey/blob/main/evaluator/evaluator.go"
    click Compiler "https://github.com/hyuraku/monkey/blob/main/compiler/compiler.go"
    click CodeDef "https://github.com/hyuraku/monkey/blob/main/code/code.go"
    click VM "https://github.com/hyuraku/monkey/blob/main/vm/vm.go"
    click ObjSys "https://github.com/hyuraku/monkey/blob/main/object/object.go"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef analysis fill:#FFCC00,stroke:#000,stroke-width:2px;
    classDef data fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef execution fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
