# vtereshkov/umka-lang architecture

> Architecture diagram of the GitHub repository vtereshkov/umka-lang, 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/vtereshkov/umka-lang
- Repository: https://github.com/vtereshkov/umka-lang

## Overview

##### Project Type and Purpose
- Type: A language toolchain (compiler + virtual machine) with embed API and multi-platform builds.
- Purpose:
– Compile Umka source files (.um) to bytecode
– Execute bytecode in a lightweight VM with reference-counting GC
– Offer a C API for embedding
– Provide a browser playground via Emscripten
– Ship standard library (runtime/*.um)
– Support cross‐platform builds and packaging (Homebrew, UmBox)

##### File Structure
- src/ → Compiler & VM modules (lexer, parser, semantic, codegen, VM, runtime, API).
- runtime/ → Umka standard library in Umka itself (.um), GC helpers, UTF-8 support.
- playground/umka.js, run_emscripten* → Emscripten-compiled VM for browser.
- examples/ → Embedding examples (3dcam, raytracer, Lisp).
- tests/ → Umka test suite, harness scripts.
- build_*.sh/.bat, Makefile → Cross-platform build scripts.
- .github/workflows → CI pipelines for building/testing (including UmBox packaging).
- doc/ → Language, API, library documentation.

##### README for Technical Insights
- Language features (static typing, fibers, GC).
- Embedding API (C99 static/dynamic library).
- Playground (web UI).
- Packaging (UmBox, Homebrew).
- Example integration (raylib, game frameworks).

##### Main Components & Relationships
a. Source Inputs
– Umka source files (.um) & examples
– Standard library scripts (runtime/*.um)
b. Compiler Pipeline (src/)
– Lexer → Parser → Semantic Analyzer → Intermediate Representation → Code Generator
– Produces bytecode (in‐memory or on‐disk module)
c. Virtual Machine & Runtime
– Bytecode loader/executor (src/umka_vm.c)
– Garbage collector (reference counting)
– Runtime support (memory, UTF8, math, fibers)
d. Embedding API
– C functions (src/umka_api.{h,c})
– Header/API layer exposed to hosts
e. Tooling & Packaging
– CLI tool (umka.exe/umka)
– Playground (Emscripten build: umka.js + HTML)
– Build scripts for Windows, Linux, macOS, WASM
– CI (GitHub Actions) & UmBox packaging

##### Architectural Patterns & Design Principles
- Pipeline pattern for compiler stages
- Layered architecture:
– Presentation (CLI, Playground UI)
– Processing (compiler modules)
– Execution (VM + runtime)
– Integration (C API)
- Modular C code organized by responsibility (lexer, parser, stmt, expr, gen, vm, runtime, API)
- Cross-compilation targets via build scripts and Emscripten wrapper
- Test harness drives compiler + VM on sample scripts

##### Final Checklist
[ ] All major components labeled
[ ] Notes on key technologies (C99, Emscripten, reference-count GC)
[ ] Representation of tests and CI as validation lanes (optional)
[ ] Clear separation of layers: Input → Compile → Execute → Embed → Deploy

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Sources"
        direction TB
        Examples["Examples"]:::input
        StdLib["Standard Library (.um)"]:::input
        Benchmarks["Benchmarks"]:::input
    end

    %% Compiler Pipeline
    subgraph "Compiler Pipeline"
        direction TB
        Driver["Compiler Driver\n(src/umka_compiler.c)"]:::compile
        Lexer["Lexer\n(src/umka_lexer.c)"]:::compile
        Ident["Identifier & Symbol Table\n(src/umka_ident.c)"]:::compile
        Expr["Expressions\n(src/umka_expr.c)"]:::compile
        Stmt["Statements\n(src/umka_stmt.c)"]:::compile
        Decl["Semantic Analyzer\n(src/umka_decl.c)"]:::compile
        ConstFold["Constant Folding\n(src/umka_const.c)"]:::compile
        TypeCheck["Type Checking\n(src/umka_types.c)"]:::compile
        CodeGen["Code Generator\n(src/umka_gen.c)"]:::compile
        Common["Common Utilities\n(src/umka_common.c)"]:::compile
    end

    %% Execution Layer
    subgraph "Execution (VM & Runtime)"
        direction TB
        Bytecode["Bytecode Storage"]:::storage
        VMCore["VM Core & Executor\n(src/umka_vm.c)"]:::execution
        GCRuntime["GC & Runtime Support\n(src/umka_runtime.c)"]:::execution
    end

    %% Embedding API
    subgraph "Embedding API"
        direction TB
        APIHeader["API Header\n(src/umka_api.h)"]:::api
        APIImpl["API Implementation\n(src/umka_api.c)"]:::api
        HostApp["Host Application"]:::external
    end

    %% Tooling & Packaging
    subgraph "Tooling & Packaging"
        direction TB
        CLI["CLI Tool Main\n(src/umka.c)"]:::tool
        Playground["Playground (Emscripten)\n(playground/umka.js)"]:::tool
        BuildScripts["Build Scripts\n(Makefile, *.sh, *.bat)"]:::tool
        CI["CI Workflows\n(.github/workflows)"]:::tool
        UmBox["UmBox Packaging\n(box.json, scripts)"]:::tool
    end

    %% Connections: Inputs to Compiler
    Examples -->|".um files"| Driver
    StdLib -->|"runtime scripts"| Driver
    Benchmarks -->|".um benchmarks"| Driver

    %% Compiler Sequence
    Driver -->|"tokens"| Lexer
    Lexer -->|"AST"| Ident
    Ident -->|"AST"| Expr
    Expr -->|"AST"| Stmt
    Stmt -->|"AST"| Decl
    Decl -->|"AST/IR"| ConstFold
    ConstFold -->|"IR"| TypeCheck
    TypeCheck -->|"typed IR"| CodeGen
    CodeGen -->|"bytecode"| Common
    Common -->|"final bytecode"| Bytecode

    %% Execution Flow
    Bytecode -->|"loads"| VMCore
    VMCore -->|"executes"| GCRuntime

    %% Embedding Flow
    HostApp -->|"calls"| APIHeader
    APIHeader -->|"invokes"| APIImpl
    APIImpl -->|"controls"| VMCore

    %% Tooling Flow
    BuildScripts --> CLI
    BuildScripts --> Playground
    CI --> BuildScripts
    CI --> UmBox
    Playground -->|"web UI"| HostApp

    %% Click Events for component mapping
    click Examples "https://github.com/vtereshkov/umka-lang/tree/master/examples/"
    click StdLib "https://github.com/vtereshkov/umka-lang/blob/master/runtime/std.um"
    click Benchmarks "https://github.com/vtereshkov/umka-lang/tree/master/benchmarks/"
    click Driver "https://github.com/vtereshkov/umka-lang/blob/master/src/umka_compiler.c"
    click Lexer "https://github.com/vtereshkov/umka-lang/blob/master/src/umka_lexer.c"
    click Ident "https://github.com/vtereshkov/umka-lang/blob/master/src/umka_ident.c"
    click Expr "https://github.com/vtereshkov/umka-lang/blob/master/src/umka_expr.c"
    click Stmt "https://github.com/vtereshkov/umka-lang/blob/master/src/umka_stmt.c"
    click Decl "https://github.com/vtereshkov/umka-lang/blob/master/src/umka_decl.c"
    click ConstFold "https://github.com/vtereshkov/umka-lang/blob/master/src/umka_const.c"
    click TypeCheck "https://github.com/vtereshkov/umka-lang/blob/master/src/umka_types.c"
    click CodeGen "https://github.com/vtereshkov/umka-lang/blob/master/src/umka_gen.c"
    click Common "https://github.com/vtereshkov/umka-lang/blob/master/src/umka_common.c"
    click Bytecode "https://github.com/vtereshkov/umka-lang/blob/master/src/umka_vm.c"
    click VMCore "https://github.com/vtereshkov/umka-lang/blob/master/src/umka_vm.c"
    click GCRuntime "https://github.com/vtereshkov/umka-lang/blob/master/src/umka_runtime.c"
    click APIHeader "https://github.com/vtereshkov/umka-lang/blob/master/src/umka_api.h"
    click APIImpl "https://github.com/vtereshkov/umka-lang/blob/master/src/umka_api.c"
    click CLI "https://github.com/vtereshkov/umka-lang/blob/master/src/umka.c"
    click Playground "https://github.com/vtereshkov/umka-lang/blob/master/playground/umka.js"
    click BuildScripts "https://github.com/vtereshkov/umka-lang/tree/master/Makefile"
    click CI "https://github.com/vtereshkov/umka-lang/blob/master/.github/workflows/main.yml"
    click UmBox "https://github.com/vtereshkov/umka-lang/blob/master/box.json"

    %% Styles
    classDef input fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef compile fill:#d0e1f9,stroke:#333,stroke-width:1px
    classDef storage fill:#f9e2d0,stroke:#333,stroke-width:1px,shape:cylinder
    classDef execution fill:#d1f9d8,stroke:#333,stroke-width:1px
    classDef api fill:#f9f1d0,stroke:#333,stroke-width:1px
    classDef external fill:#eee,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef tool fill:#f0d9f0,stroke:#333,stroke-width:1px
```
