# bellard/quickjs architecture

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

- Interactive diagram: https://gitdiagram.com/bellard/quickjs
- Repository: https://github.com/bellard/quickjs

## Overview

##### Main Components
- Core Engine: This includes files like qjs.c, quickjs.c, and quickjs-libc.c. They form the central engine responsible for parsing, bytecode generation (handled by qjsc.c), interpretation, and the runtime (including garbage collection, execution, etc.).
- Parser & Compiler: Highlight the modules that handle parsing JavaScript code and compiling it into bytecode (with qjsc.c acting as the compiler front-end).
- Runtime System: This includes components like the interpreter loop, runtime environment, and built-in objects/methods implemented inside the core files.
- Standard Library & Extensions:
– Built-in C library integration (quickjs-libc*).
– Extended functional modules such as the regex engine (libregexp.c/h) and Unicode support (libunicode.c/h).
– Utility routines (e.g., dtoa.c/dtoa.h for number conversions, cutils.c/h).
- Testing and Fuzzing: Represent the separate directories “tests” and “fuzz” as components that are used for validation and ensuring the robustness of the engine.
- Examples: The “examples” folder is meant to showcase how to integrate or use QuickJS (showing both pure JS and hybrid usage with C modules).

- Execution Flow: From the bytecode representation, show a directional flow to the “Interpreter/Runtime” component, which contains the execution loop, garbage collector, and environment management.
- Testing and Quality Assurance: Represent the “tests” and “fuzz” directories as side modules that feed test cases and fuzzing inputs back into the engine components to ensure integrity.

##### Architectural Patterns and Design Principles
- Modular Design: Emphasize how each distinct responsibility (parsing, execution, library support) has its own set of files and directories.
- Extensibility: Note the separation between the core engine and extensions (e.g., regex, Unicode) to allow replacing or updating these components independently.
- Separation of Concerns: The division between the JS execution engine and the host interfaces (like quickjs-libc) reinforces clear boundaries.
- Testing as a First-Class Citizen: Including robust testing and fuzzing indicates continuous integration which should be part of your overall architecture view.

##### Relevant Technologies and Libraries
- C as the primary implementation language.
- Use of Makefile for builds indicates that the build and configuration process is central and should be noted.
- The integration of Test262 tests suggests compliance with JavaScript standards.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input
    JS_Input["JavaScript Source Code"]:::input

    %% Parser & Compiler
    QJSC["qjsc.c"]:::compiler

    %% Bytecode / AST Representation
    Bytecode["Bytecode/AST Representation"]:::data

    %% Core Engine & Runtime Subgraph
    subgraph "Core Engine & Runtime"
        QJS["qjs.c"]:::core
        QUICKJS["quickjs.c"]:::core
        QUICKJS_LIBC["quickjs-libc.c"]:::core
    end

    %% Standard Library & Extensions Subgraph
    subgraph "Standard Library & Extensions"
        %% Built-in C Library Integration
        subgraph "Built-in C Library"
            QUICKJS_LIBC_H["quickjs-libc.h"]:::lib
        end
        %% Regex Engine
        subgraph "Regex Engine"
            LIBREGEXP_C["libregexp.c"]:::lib
            LIBREGEXP_H["libregexp.h"]:::lib
            LIBREGEXP_OPCODE["libregexp-opcode.h"]:::lib
        end
        %% Unicode Support
        subgraph "Unicode Support"
            LIBUNICODE_C["libunicode.c"]:::lib
            LIBUNICODE_H["libunicode.h"]:::lib
            LIBUNICODE_TABLE["libunicode-table.h"]:::lib
        end
        %% Utility Routines
        subgraph "Utility Routines"
            DTOA_C["dtoa.c"]:::lib
            DTOA_H["dtoa.h"]:::lib
            CUTILS_C["cutils.c"]:::lib
            CUTILS_H["cutils.h"]:::lib
        end
    end

    %% Testing & Fuzzing Subgraph
    subgraph "Testing & Fuzzing"
        TESTS["Tests Directory"]:::test
        FUZZ["Fuzz Directory"]:::test
    end

    %% Examples Subgraph
    subgraph "Examples"
        EXAMPLES["Examples Directory"]:::example
    end

    %% External / Host Interface and Build System
    HostApp["Host Application / Embedding API"]:::external
    BUILD["Build System (Makefile)"]:::build

    %% Data Flow Connections
    JS_Input -->|"parses"| QJSC
    QJSC -->|"generates"| Bytecode
    Bytecode -->|"executes"| QJS

    %% Host embedding connection
    HostApp -->|"embeds"| QJS

    %% Build system connection
    BUILD -->|"builds"| QJS

    %% Runtime uses standard libraries/extensions
    QJS -->|"uses"| QUICKJS_LIBC_H
    QJS -->|"uses"| LIBREGEXP_C
    QJS -->|"uses"| LIBUNICODE_C
    QJS -->|"uses"| DTOA_C

    %% Testing & Fuzzing input into Engine
    TESTS -->|"tests"| QJS
    FUZZ -->|"fuzzes"| QJS

    %% Examples interact with Host API
    EXAMPLES -->|"demonstrates"| HostApp

    %% Click Events
    click QJS "https://github.com/bellard/quickjs/blob/master/qjs.c"
    click QUICKJS "https://github.com/bellard/quickjs/blob/master/quickjs.c"
    click QUICKJS_LIBC "https://github.com/bellard/quickjs/blob/master/quickjs-libc.c"
    click QJSC "https://github.com/bellard/quickjs/blob/master/qjsc.c"
    click QUICKJS_LIBC_H "https://github.com/bellard/quickjs/blob/master/quickjs-libc.h"
    click LIBREGEXP_C "https://github.com/bellard/quickjs/blob/master/libregexp.c"
    click LIBREGEXP_H "https://github.com/bellard/quickjs/blob/master/libregexp.h"
    click LIBREGEXP_OPCODE "https://github.com/bellard/quickjs/blob/master/libregexp-opcode.h"
    click LIBUNICODE_C "https://github.com/bellard/quickjs/blob/master/libunicode.c"
    click LIBUNICODE_H "https://github.com/bellard/quickjs/blob/master/libunicode.h"
    click LIBUNICODE_TABLE "https://github.com/bellard/quickjs/blob/master/libunicode-table.h"
    click DTOA_C "https://github.com/bellard/quickjs/blob/master/dtoa.c"
    click DTOA_H "https://github.com/bellard/quickjs/blob/master/dtoa.h"
    click CUTILS_C "https://github.com/bellard/quickjs/blob/master/cutils.c"
    click CUTILS_H "https://github.com/bellard/quickjs/blob/master/cutils.h"
    click TESTS "https://github.com/bellard/quickjs/tree/master/tests"
    click FUZZ "https://github.com/bellard/quickjs/tree/master/fuzz"
    click EXAMPLES "https://github.com/bellard/quickjs/tree/master/examples"

    %% Styling
    classDef input fill:#FFECB3,stroke:#BF360C,stroke-width:2px;
    classDef compiler fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef data fill:#E1F5FE,stroke:#0288D1,stroke-width:2px;
    classDef core fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef lib fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef test fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef example fill:#B2DFDB,stroke:#00796B,stroke-width:2px;
    classDef external fill:#BBDEFB,stroke:#1976D2,stroke-width:2px;
    classDef build fill:#F0F4C3,stroke:#827717,stroke-width:2px;
```
