# lemon-lang/lemon architecture

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

- Interactive diagram: https://gitdiagram.com/lemon-lang/lemon
- Repository: https://github.com/lemon-lang/lemon

## Overview

##### Project type and purpose
- This is a language implementation project: the Lemon Programming Language. It contains both a compiler and a virtual machine (VM), along with core libraries for the language.
- Key indicators:
- src/: source code for compiler front-end, code generator, VM (“machine”), memory management, and REPL shell
- lib/: built-in libraries (OS and socket support)
- test/: sample programs to validate compilation and execution

##### File structure
- Top-level:
- src/ – compiler and VM implementation in C
- lib/ – core runtime libraries for OS and socket modules
- doc/ – documentation of source code and design rationale
- test/ – lemon source files for unit testing
- Makefile, VERSION, LICENSE, README.md
- Patterns and architectural choices:
- Compiler broken into lexer (lexer.c/token.c), parser (parser.c/syntax.c), semantic scope (scope.c/symbol.c), AST manipulation, peephole optimizer, code generator (generator.c), and output of bytecode (opcode.c)
- VM separated into memory allocator (allocator.c, arena.c, mpool.c), garbage collector (collector.c), interpreter loop (machine.c), and built-in object implementations (lstring.c, larray.c, etc.)
- Shell (shell.c) as REPL front-end invoking compiler + VM

##### README for additional insights
- README clarifies build flags controlling debug, static linking, malloc wrapper, and enabling OS/socket modules.

a. Main components
1. Front-end Compiler
– Lexer & Tokenizer
– Parser & AST builder
– Semantic Analyzer & Scope Manager
– Intermediate Representation & Peephole Optimizer
– Bytecode Generator (generator.c + opcode definitions)
2. Virtual Machine
– Memory Management (allocator, arena, mpool)
– Garbage Collector (collector)
– Interpreter Loop (machine)
– Built-in Object Implementations (lstring, larray, etc.)
3. Core Libraries (lib/)
– OS Module (lib/os.c, lib/os.h)
– Socket Module (lib/socket.c, lib/socket.h)
4. REPL Shell (shell.c)
5. Test Harness (test/*.lm)
6. Build System (Makefile)

b. Relationships and interactions
– Source File (.lm) enters REPL Shell or CLI driver (main.c)
– Driver invokes Compiler Front-end
→ passes code through Lexer → Parser → Semantic Analyzer → IR → Bytecode Generator
– Generated Bytecode passed into VM Interpreter
→ VM uses Memory Manager + GC to allocate objects
→ VM executes bytecode instructions, calling built-in implementations or external libs
– OS/Socket modules are dynamically linked (or statically if STATIC=1) and invoked via VM built-ins
– Test harness automates invocation of compiler+VM and verifies output

c. Architectural patterns and design principles
– Modular separation: front-end vs VM vs built-ins
– Layered architecture:
1. Presentation (shell/main driver)
2. Compilation pipeline
3. Execution engine
4. Runtime libraries
– Pluggable modules: OS and socket support toggled at build time
– Memory safety via custom allocator and garbage collector

d. Key technologies/frameworks/libraries
– ANSI C99 for all components
– Makefile for build orchestration
– No external dependencies beyond standard C library and POSIX/BSD socket APIs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Input
    SourceFile["Lemon Source File (.lm)"]:::external

    %% Presentation Layer
    subgraph "Presentation Layer"
        REPL["REPL Shell"]:::compile
        Driver["CLI Driver (main.c)"]:::compile
    end

    %% Compilation Pipeline
    subgraph "Compiler Front-end" 
        Lexer["Lexer & Tokenizer"]:::compile
        Parser["Parser & AST Builder"]:::compile
        Semantic["Semantic Analyzer & Scope Manager"]:::compile
        IR["IR & Peephole Optimizer"]:::compile
        CodeGen["Bytecode Generator & Opcode Definitions"]:::compile
    end

    %% Artifact
    Bytecode["Bytecode Artifact"]:::artifact

    %% Runtime Engine
    subgraph "Virtual Machine"
        subgraph "Interpreter"
            Interpreter["Interpreter Loop"]:::runtime
        end
        subgraph "Memory Management"
            Allocator["Allocator"]:::runtime
            Arena["Arena Allocator"]:::runtime
            MPool["Memory Pool"]:::runtime
        end
        GC["Garbage Collector"]:::runtime
        Builtins["Built-in Object Impl."]:::runtime
    end

    %% Core Libraries
    subgraph "Core Libraries"
        OSModule["OS Module"]:::module
        SocketModule["Socket Module"]:::module
        BuiltinReg["Built-ins Registration"]:::module
    end

    %% Test & Build
    TestHarness["Test Harness (.lm)"]:::external
    BuildSystem["Build System (Makefile)"]:::external

    %% Flows
    SourceFile -->|reads| REPL
    SourceFile -->|reads| Driver
    REPL -->|invokes| Driver
    Driver -->|runs| Lexer
    Lexer -->|token stream| Parser
    Parser -->|AST| Semantic
    Semantic -->|IR| IR
    IR -->|optimized IR| CodeGen
    CodeGen -->|bytecode| Bytecode
    Bytecode -->|executes| Interpreter
    Interpreter -->|alloc/free| Allocator
    Interpreter -->|alloc/free| Arena
    Interpreter -->|alloc/free| MPool
    Interpreter -->|trigger| GC
    Interpreter -->|calls| Builtins
    Builtins -->|use| OSModule
    Builtins -->|use| SocketModule
    Driver -->|builds| BuildSystem
    Driver -->|runs tests| TestHarness

    %% Click Events
    click Lexer "https://github.com/lemon-lang/lemon/blob/master/src/lexer.c"
    click Parser "https://github.com/lemon-lang/lemon/blob/master/src/parser.c"
    click Semantic "https://github.com/lemon-lang/lemon/blob/master/src/scope.c"
    click IR "https://github.com/lemon-lang/lemon/blob/master/src/peephole.c"
    click CodeGen "https://github.com/lemon-lang/lemon/blob/master/src/generator.c"
    click Driver "https://github.com/lemon-lang/lemon/blob/master/src/main.c"
    click Interpreter "https://github.com/lemon-lang/lemon/blob/master/src/machine.c"
    click Allocator "https://github.com/lemon-lang/lemon/blob/master/src/allocator.c"
    click GC "https://github.com/lemon-lang/lemon/blob/master/src/collector.c"
    click Builtins "https://github.com/lemon-lang/lemon/blob/master/src/lstring.c"
    click REPL "https://github.com/lemon-lang/lemon/blob/master/src/shell.c"
    click OSModule "https://github.com/lemon-lang/lemon/blob/master/lib/os.c"
    click SocketModule "https://github.com/lemon-lang/lemon/blob/master/lib/socket.c"
    click TestHarness "https://github.com/lemon-lang/lemon/blob/master/test/test.lm"
    click BuildSystem "https://github.com/lemon-lang/lemon/tree/master/Makefile"

    %% Styles
    classDef compile fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1
    classDef runtime fill:#E8F5E9,stroke:#43A047,color:#1B5E20
    classDef module fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef external fill:#FFEBEE,stroke:#E53935,color:#B71C1C
    classDef artifact fill:#ECEFF1,stroke:#607D8B,color:#263238
```
