# jawad-ch/go-interpreter architecture

> Architecture diagram of the GitHub repository jawad-ch/go-interpreter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jawad-ch/go-interpreter
- Repository: https://github.com/jawad-ch/go-interpreter

## Overview

##### Project type and purpose
- This is a small programming-language implementation written in Go (from Thorsten Ball’s “Writing an Interpreter in Go”).
- It provides both an AST-based interpreter (evaluator) and a compiler that emits bytecode for a stack-based VM, along with a REPL and benchmarks.

##### File structure
- Top-level Go modules and directories:
- token, lexer, parser – the front-end: tokenization → parsing → AST
- ast – the abstract syntax tree definitions
- evaluator – direct AST interpreter (walks AST, produces objects)
- compiler – bytecode emitter (symbol_table, code)
- vm – virtual machine (frame, stack, instruction execution)
- object – runtime objects and built-in definitions
- repl – interactive shell tying everything together
- benchmark – performance harness
- Config: go.mod
- Main entrypoint: main.go (invokes either REPL or compiles/runs files)

##### README for additional insights
- The README simply attributes the source to Thorsten Ball; no extra architecture notes
- However, the code layout signals a classic compiler pipeline with an alternate interpreter path

##### Detail everything without overthinking
- Break each module into as many subcomponents as helpful (e.g., symbol_table vs code in compiler)
- Notable functions (e.g., NextToken in lexer; ParseProgram in parser; Emit in compiler; Run in VM)
- If space permits, add small notes about test coverage for each module

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Entrypoint
    Main["main.go"]:::external
    click Main "https://github.com/jawad-ch/go-interpreter/blob/main/main.go"

    %% REPL and Benchmark
    Main -->|chooses| REPL["REPL / Interactive Shell"]:::external
    click REPL "https://github.com/jawad-ch/go-interpreter/blob/main/repl/repl.go"
    Main -->|runs| Benchmark["Benchmark Harness"]:::external
    click Benchmark "https://github.com/jawad-ch/go-interpreter/blob/main/benchmark/main.go"

    %% REPL Pipeline
    REPL --> FrontEnd

    subgraph "Front-end" 
        direction TB
        Token["Token Module"]:::frontend
        click Token "https://github.com/jawad-ch/go-interpreter/blob/main/token/token.go"
        Lexer["Lexer"]:::frontend
        click Lexer "https://github.com/jawad-ch/go-interpreter/blob/main/lexer/lexer.go"
        Parser["Parser"]:::frontend
        click Parser "https://github.com/jawad-ch/go-interpreter/blob/main/parser/parser.go"
        AST["AST Definitions"]:::frontend
        click AST "https://github.com/jawad-ch/go-interpreter/blob/main/ast/ast.go"
        Token -->|tokens| Lexer
        Lexer -->|tokens| Parser
        Parser -->|AST| AST
    end

    %% Interpreter Back-end
    AST --> Interpreter
    subgraph "Interpreter (AST Evaluator)"
        direction TB
        EvalCore["AST Interpreter"]:::interpreter
        click EvalCore "https://github.com/jawad-ch/go-interpreter/blob/main/evaluator/evaluator.go"
        EvalBuiltins["Evaluator Built-ins"]:::interpreter
        click EvalBuiltins "https://github.com/jawad-ch/go-interpreter/blob/main/evaluator/builtins.go"
        EvalCore -->|uses| EvalBuiltins
        EvalCore -->|produces| ObjectStore
    end
    Interpreter --> EvalCore

    %% Compiler + VM Back-end
    AST --> CompilerPipeline
    subgraph "Compiler + VM"
        direction TB
        subgraph "Compiler" 
            direction TB
            CompilerCore["Compiler (Bytecode Emitter)"]:::compiler
            click CompilerCore "https://github.com/jawad-ch/go-interpreter/blob/main/compiler/compiler.go"
            SymTable["Symbol Table"]:::compiler
            click SymTable "https://github.com/jawad-ch/go-interpreter/blob/main/compiler/symbol_table.go"
            CodeGen["Bytecode Definitions & Code Generator"]:::compiler
            click CodeGen "https://github.com/jawad-ch/go-interpreter/blob/main/code/code.go"
            CompilerCore -->|symbol lookup| SymTable
            CompilerCore -->|emit bytecode| CodeGen
        end
        CodeGen --> Bytecode["Bytecode"]:::compiler
        Bytecode --> VMCore
        subgraph "Virtual Machine"
            direction TB
            VMCore["VM Core"]:::vm
            click VMCore "https://github.com/jawad-ch/go-interpreter/blob/main/vm/vm.go"
            VMFrame["VM Frame Management"]:::vm
            click VMFrame "https://github.com/jawad-ch/go-interpreter/blob/main/vm/frame.go"
            VMCore -->|manages| VMFrame
            VMCore -->|executes| ObjectStore
        end
    end

    %% Runtime Object Store
    ObjectStore["Object Store / Heap"]:::runtime
    click ObjectStore "https://github.com/jawad-ch/go-interpreter/blob/main/object/object.go"
    ObjectBuiltins["Object Built-ins"]:::runtime
    click ObjectBuiltins "https://github.com/jawad-ch/go-interpreter/blob/main/object/builtins.go"
    ObjectStore -->|includes| ObjectBuiltins

    %% Benchmark paths
    Benchmark -->|uses front-end| FrontEnd
    Benchmark -->|uses interpreter| EvalCore
    Benchmark -->|uses VM| VMCore

    %% Classes
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef interpreter fill:#E2F0D9,stroke:#2E7D32,color:#2E7D32;
    classDef compiler fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
    classDef vm fill:#FFF3E0,stroke:#F57C00,color:#BF360C;
    classDef runtime fill:#E0E0E0,stroke:#757575,color:#424242;
    classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C;
```
