# kuroko-lang/kuroko architecture

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

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

## Overview

##### Project Type and Purpose
- Kuroko is a programming‐language implementation: a dynamic, bytecode-compiled Python dialect.
- It provides a compiler (turns KrK source into bytecode), a VM/interpreter (executes bytecode), a REPL/CLI, a C API for embedding, plus standard library modules and tooling.

##### High-Level Architecture Components
a. Build System
- Makefile + GitHub workflows → compiles C sources into:
– kuroko CLI executable (integrates compiler + VM)
– libkuroko.{a,so} shared/static library for embedding
b. Compiler Frontend
- src/compiler.c, src/scanner.c, src/kuroko/*.h → parse KrK source, generate bytecode chunks
c. Virtual Machine & Runtime
- src/vm.c, src/memory.c, GC (tracing collector), threading support (src/threads.c)
- Core interpreter loop, opcode definitions (src/opcodes.h), object model (src/object.c, src/obj_*.c)
d. Builtin and Extension Modules
- src/modules/*.{c,krk} → C‐based modules (math, os, socket, etc.)
- modules/*.krk → standard library in KrK scripts
e. REPL/CLI Layer
- kuroko binary: wires together the frontend, VM, line editor, disassembler (if enabled)
f. Embedding API
- public headers (src/kuroko/*.h) → host applications link against libkuroko to embed interpreter
g. Tools, Benchmarks, Testing & Documentation
- tools/ → utility programs (e.g., code generators, sandbox)
- bench/ → performance tests comparing bytecode vs. Python
- test/ → comprehensive KrK test suite
- docs/ → Doxygen config+ markdown user/embedding/compiler docs

##### Interactions and Data Flow
- KrK source file → (CLI or embedding host) → Compiler Frontend → Bytecode
- Bytecode → Virtual Machine → Executes instructions, allocates/traces objects, schedules threads
- VM loads modules on import: either C‐based (dynamically linked) or KrK scripts
- REPL feeds source lines into the compiler, then executes via VM
- Host application → C API calls to initialize VM, load scripts/modules, run bytecode

##### Architectural Patterns & Principles
- Layered design: clear separation between parsing/compilation, runtime engine, and embedding interface
- Modular extensibility: additional modules in C or KrK; third‐party embedding via stable C ABI
- Configurable build flags control features (debugging, docs, line editor)

5. Off of VM, show “Standard Library” layer split into:
– C Extension Modules (src/modules)
– KrK Module Scripts (modules/)

##### Final Touches
- Build‐time flags and supported platforms

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Components
    Build["Build System / CI"]:::neutral
    Source["KrK Source Files"]:::neutral
    Compiler["Compiler Frontend"]:::core
    Bytecode["Bytecode Format"]:::core
    VM["VM & Runtime\n(GC, Scheduler,\nOpcode Dispatcher)"]:::core

    %% Standard Library
    subgraph "Standard Library"
        CModules["C Extension Modules"]:::lib
        KrKModules["KrK Module Scripts"]:::lib
    end

    %% Interfaces
    REPL["REPL / CLI"]:::interface
    Embed["Embedding Host Interface"]:::interface

    %% Tools, Bench, Tests, Docs
    Tools["Tools"]:::neutral
    Bench["Benchmarks"]:::neutral
    Tests["Test Harness"]:::neutral
    Docs["Documentation"]:::neutral

    %% Data Flow
    Source -->|"KrK source"| Compiler
    Compiler -->|"bytecode file"| Bytecode
    Bytecode -->|"executes"| VM
    VM <-->|"loads modules"| CModules
    VM <-->|"loads scripts"| KrKModules
    REPL -->|"compile & exec"| Compiler
    REPL -->|"runtime"| VM
    Embed -.->|"C API call"| VM

    %% Build outputs
    Build -->|"produces CLI & libkuroko"| REPL
    Build -->|"produces CLI & libkuroko"| Embed

    %% Auxiliary
    Tools -.->|"utility programs"| Compiler
    Tools -.->|"utility programs"| VM
    Bench -.->|"performance tests"| VM
    Tests -.->|"test suite"| REPL
    Docs -.->|"docs & API reference"| Embed

    %% Click Events
    click Build "https://github.com/kuroko-lang/kuroko/tree/master/Makefile"
    click Build "https://github.com/kuroko-lang/kuroko/blob/master/.github/workflows/build.yml"
    click Build "https://github.com/kuroko-lang/kuroko/blob/master/.github/workflows/codeql-analysis.yml"
    click Compiler "https://github.com/kuroko-lang/kuroko/blob/master/src/compiler.c"
    click Compiler "https://github.com/kuroko-lang/kuroko/blob/master/src/scanner.c"
    click Compiler "https://github.com/kuroko-lang/kuroko/blob/master/src/kuroko/compiler.h"
    click Compiler "https://github.com/kuroko-lang/kuroko/blob/master/src/kuroko/scanner.h"
    click Compiler "https://github.com/kuroko-lang/kuroko/blob/master/src/kuroko/chunk.h"
    click Compiler "https://github.com/kuroko-lang/kuroko/blob/master/src/chunk.c"
    click Bytecode "https://github.com/kuroko-lang/kuroko/blob/master/src/chunk.c"
    click Bytecode "https://github.com/kuroko-lang/kuroko/blob/master/src/kuroko/chunk.h"
    click Bytecode "https://github.com/kuroko-lang/kuroko/blob/master/src/opcode_enum.h"
    click Bytecode "https://github.com/kuroko-lang/kuroko/blob/master/src/opcodes.h"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/vm.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/memory.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/threads.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/kuroko/vm.h"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/kuroko/memory.h"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/kuroko/threads.h"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/object.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/obj_base.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/obj_bytes.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/obj_dict.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/obj_function.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/obj_gen.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/obj_list.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/obj_long.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/obj_numeric.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/obj_range.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/obj_set.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/obj_slice.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/obj_str.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/obj_tuple.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/obj_typing.c"
    click VM "https://github.com/kuroko-lang/kuroko/blob/master/src/table.c"
    click CModules "https://github.com/kuroko-lang/kuroko/blob/master/src/modules/module_math.c"
    click CModules "https://github.com/kuroko-lang/kuroko/blob/master/src/modules/module_os.c"
    click CModules "https://github.com/kuroko-lang/kuroko/blob/master/src/modules/module_socket.c"
    click CModules "https://github.com/kuroko-lang/kuroko/blob/master/src/modules/module_time.c"
    click CModules "https://github.com/kuroko-lang/kuroko/blob/master/src/modules/module_random.c"
    click CModules "https://github.com/kuroko-lang/kuroko/blob/master/src/modules/module_gc.c"
    click CModules "https://github.com/kuroko-lang/kuroko/tree/master/src/modules/"
    click CModules "https://github.com/kuroko-lang/kuroko/tree/master/modules/"
    click KrKModules "https://github.com/kuroko-lang/kuroko/tree/master/modules/"
    click REPL "https://github.com/kuroko-lang/kuroko/blob/master/src/kuroko.c"
    click REPL "https://github.com/kuroko-lang/kuroko/blob/master/src/debug.c"
    click REPL "https://github.com/kuroko-lang/kuroko/blob/master/src/parseargs.c"
    click Embed "https://github.com/kuroko-lang/kuroko/blob/master/src/kuroko/kuroko.h"
    click Embed "https://github.com/kuroko-lang/kuroko/blob/master/src/kuroko/value.h"
    click Embed "https://github.com/kuroko-lang/kuroko/blob/master/src/kuroko/object.h"
    click Embed "https://github.com/kuroko-lang/kuroko/blob/master/src/kuroko/util.h"
    click Embed "https://github.com/kuroko-lang/kuroko/blob/master/src/kuroko/table.h"
    click Embed "https://github.com/kuroko-lang/kuroko/blob/master/src/kuroko/scanner.h"
    click Embed "https://github.com/kuroko-lang/kuroko/blob/master/src/kuroko/debug.h"
    click Tools "https://github.com/kuroko-lang/kuroko/tree/master/tools/"
    click Bench "https://github.com/kuroko-lang/kuroko/blob/master/bench/bench.krk"
    click Bench "https://github.com/kuroko-lang/kuroko/blob/master/bench/bench.py"
    click Bench "https://github.com/kuroko-lang/kuroko/tree/master/bench/fasttimer/"
    click Tests "https://github.com/kuroko-lang/kuroko/tree/master/test/"
    click Docs "https://github.com/kuroko-lang/kuroko/tree/master/docs/Doxyfile"
    click Docs "https://github.com/kuroko-lang/kuroko/blob/master/docs/embedding.md"
    click Docs "https://github.com/kuroko-lang/kuroko/blob/master/docs/lang_compiler.md"
    click Docs "https://github.com/kuroko-lang/kuroko/blob/master/docs/doxygen_header.html"
    click Docs "https://github.com/kuroko-lang/kuroko/blob/master/docs/doxygen_footer.html"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#1B4F72,stroke-width:1px
    classDef lib fill:#DFF2BF,stroke:#4F8A10,stroke-width:1px
    classDef interface fill:#FFD7D9,stroke:#8A1B1B,stroke-width:1px
    classDef neutral fill:#F0F0F0,stroke:#888888,stroke-width:1px
```
