# guille-ux/zynklite architecture

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

- Interactive diagram: https://gitdiagram.com/guille-ux/zynklite
- Repository: https://github.com/guille-ux/zynklite

## Overview

##### Project type and purpose
- Zynk Lite is a lightweight, embeddable scripting language implemented in Python (with a future C target).
- It provides both an interpreter and (in progress) a bytecode compiler.

##### File structure
- Top‐level:
- zynk-lite/ — the actual language implementation and packaging
- zynk-lite/src/zynk_lite/
- frontend/ (lexer.py)
- ast/ (parser.py, expressions.py, eval.py, zenv.py)
- bytecode/ (bytecode definitions)
- compiler.py
- interpreter.py
- cli.py (entry‐point)
- native_funcs/ (built‐in host functions)
- tokens.py, errors.py
- Configuration & build: pyproject.toml, build.sh, dist/
- Tests: zynk-lite/tests/

##### Key insights from the README
- Provides both CLI and Python API interfaces.
- Stages in roadmap: interpreter → bytecode compiler → C transpiler.
- Core features: lexer, parser, AST evaluator, native I/O, modular imports.

##### Main components & interactions
a. Components
1. CLI / Python API layer (cli.py, dev.py)
2. Frontend (lexer → parser)
3. AST module (expressions, eval, environment)
4. Interpreter engine (immediate AST execution)
5. Compiler engine (AST→bytecode)
6. Bytecode runner / VM (executes bytecode)
7. Native functions module (file I/O, sleep, arrays)
8. Host environment (Python runtime, OS file system)
9. Packaging & distribution (build scripts, wheel/tar.gz)
10. Test harness
b. Interactions & data flows
- User input or script file → CLI/Python API
- CLI invokes Frontend → produces AST
- Two parallel flows from AST:
- AST → Interpreter → Native functions → Host
- AST → Compiler → Bytecode → VM → Native functions → Host
- All flows return results to CLI or embedding Python program
- Packaging tools read src → produce distribution artifacts
- Tests invoke CLI/API and validate outputs

##### Architectural patterns & design principles
- Compiler pipeline: clear stages (lexing, parsing, AST generation, code generation, execution)
- Modular design: separate folders for each stage
- Embeddability: CLI and direct Python API share the same core modules
- Extensibility: native_funcs as plugin point for host operations

##### Technologies & frameworks
- Python 3.6+ (runtime for all components)
- Hatch/pyproject.toml for packaging
- Bash for install scripts (mimes)
- pytest or unittest (in tests/)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Input["User Script / CLI Input"]:::external

    subgraph "CLI / API Layer"
        CLI["cli.py"]:::cli
        DEV["dev.py"]:::cli
    end

    subgraph "Frontend"
        LEXER["lexer.py"]:::frontend
        PARSER["parser.py"]:::frontend
    end

    subgraph "AST Module"
        AST["AST"]:::astBox
        EXPR["expressions.py"]:::ast
        EVAL["eval.py"]:::ast
        ZENV["zenv.py"]:::ast
    end

    subgraph "Execution Engines"
        INTERP["interpreter.py"]:::interpreter
        COMP["compiler.py"]:::compiler
        CTRANS["C Transpiler (Future)"]:::future
    end

    subgraph "Bytecode & VM"
        BC_DEF["bytecode/__init__.py"]:::bytecode
        BC["Bytecode"]:::bytecodeBox
        VM["VM Execution"]:::bytecodeBox
    end

    subgraph "Native Functions"
        NATIVE["core.py"]:::native
    end

    subgraph "Host Environment"
        HOST["Python Runtime / OS FS"]:::host
    end

    subgraph "Packaging & Distribution"
        PYPR["pyproject.toml"]:::pack
        BUILD["build.sh"]:::pack
        DIST["dist/"]:::pack
    end

    subgraph "Test Harness"
        TEST["tests/"]:::tests
    end

    Input --> CLI
    CLI --> DEV
    CLI --> LEXER
    LEXER -->|"Token Stream"| PARSER
    PARSER -->|"AST"| AST
    AST --> EXPR
    AST --> EVAL
    AST --> ZENV
    AST -->|"AST"| INTERP
    AST -->|"AST"| COMP
    COMP --> CTRANS
    COMP -->|"Bytecode"| BC
    BC --> VM
    INTERP -->|"AST Execution"| NATIVE
    VM -->|"Bytecode Execution"| NATIVE
    NATIVE -->|"Host Calls"| HOST
    PYPR -->|reads| BUILD
    BUILD -->|produces| DIST
    TEST --> CLI
    TEST --> DEV
    TEST --> INTERP
    TEST --> VM

    click CLI "https://github.com/guille-ux/zynklite/blob/master/zynk-lite/src/zynk_lite/cli.py"
    click DEV "https://github.com/guille-ux/zynklite/blob/master/zynk-lite/dev.py"
    click LEXER "https://github.com/guille-ux/zynklite/blob/master/zynk-lite/src/zynk_lite/frontend/lexer.py"
    click PARSER "https://github.com/guille-ux/zynklite/blob/master/zynk-lite/src/zynk_lite/ast/parser.py"
    click EXPR "https://github.com/guille-ux/zynklite/blob/master/zynk-lite/src/zynk_lite/ast/expressions.py"
    click EVAL "https://github.com/guille-ux/zynklite/blob/master/zynk-lite/src/zynk_lite/ast/eval.py"
    click ZENV "https://github.com/guille-ux/zynklite/blob/master/zynk-lite/src/zynk_lite/ast/zenv.py"
    click INTERP "https://github.com/guille-ux/zynklite/blob/master/zynk-lite/src/zynk_lite/interpreter.py"
    click COMP "https://github.com/guille-ux/zynklite/blob/master/zynk-lite/src/zynk_lite/compiler.py"
    click BC_DEF "https://github.com/guille-ux/zynklite/blob/master/zynk-lite/src/zynk_lite/bytecode/__init__.py"
    click NATIVE "https://github.com/guille-ux/zynklite/blob/master/zynk-lite/src/zynk_lite/native_funcs/core.py"
    click PYPR "https://github.com/guille-ux/zynklite/blob/master/zynk-lite/pyproject.toml"
    click BUILD "https://github.com/guille-ux/zynklite/blob/master/zynk-lite/build.sh"
    click DIST "https://github.com/guille-ux/zynklite/tree/master/zynk-lite/dist/"
    click TEST "https://github.com/guille-ux/zynklite/tree/master/zynk-lite/tests/"

    classDef external fill:#f2f2f2,stroke:#999
    classDef cli fill:#e0f7fa,stroke:#006064
    classDef frontend fill:#bbdefb,stroke:#0d47a1
    classDef ast fill:#c8e6c9,stroke:#1b5e20
    classDef astBox fill:#a5d6a7,stroke:#2e7d32
    classDef interpreter fill:#d1c4e9,stroke:#4a148c
    classDef compiler fill:#ffe0b2,stroke:#e65100
    classDef future fill:#ffccbc,stroke:#bf360c
    classDef bytecode fill:#d1c4e9,stroke:#4a148c
    classDef bytecodeBox fill:#b39ddb,stroke:#311b92
    classDef native fill:#f8bbd0,stroke:#880e4f
    classDef host fill:#fff9c4,stroke:#f57f17,shape:cylinder
    classDef pack fill:#d7ccc8,stroke:#4e342e
    classDef tests fill:#eceff1,stroke:#37474f
```
