# syuilo/aiscript architecture

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

## Overview

##### Project Type and Purpose
- This project is a lightweight scripting language implemented in JavaScript. It provides both a parser and an interpreter to execute scripts written in a JavaScript-like syntax, along with an optional playground (built with Vue and Vite) for live experimentation.
- The README emphasizes that AiScript supports critical language features (arrays, objects, functions, etc.), secure sandbox execution, and an easy integration process with host applications.

##### Analyzing the File Structure
- The top-level directories include key components such as:
- src: Contains the core implementation of the language.
- src/interpreter: Implements the runtime/interpreter, handling control flow, variable scopes, standard library, and execution logic.
- src/parser: Contains the parser, including scanner, token streams, syntaxes, plugins (such as validator plugins for jumping statements, keywords, and type checks), and visitor patterns.
- playground: Provides a web-based interactive UI built with Vue and configured via Vite, intended to allow online testing and demonstration of AiScript.
- test: Houses various test files to validate both the parser and interpreter functionalities.
- docs, translations, and unreleased: These directories provide documentation, localized resources, and notes about upcoming changes.
- Various configuration files (.eslintrc, tsconfig.json, GitHub workflows, etc.) are present to support coding standards, CI/CD pipelines, and project metadata.
- The file organization suggests a clear separation between the core language engine (parser and interpreter) and its demonstration/utilization (playground), along with supporting infrastructure (tests, docs, etc.).

##### Key Components
a. Core Language Engine:
- Parser Component:
- Scanner: Located in src/parser/scanner.ts.
- Token Streams: Implemented in src/parser/streams (char-stream.ts, token-stream.ts).
- Syntax Analysis: Found in src/parser/syntaxes (common, expressions, statements, etc.) and the visitor implementation (visit.ts).
- Plugins: Custom validations (plugins directory, e.g., validate-jump-statements.ts, validate-keyword.ts, validate-type.ts) which extend or ensure correct AST structure.
- Utility Functions: Helpers like src/parser/utils.ts and the token definitions in src/parser/token.ts.
- Interpreter Component:
- Core Control & Execution: Implemented in src/interpreter/control.ts.
- Standard Library: In src/interpreter/lib (e.g., std.ts).
- Runtime Environment: Includes scope management (scope.ts), variable handling (variable.ts), reference and value management, and error handling.
- Additional Interpreter Utilities: In files like primitive-props.ts, reference.ts, and src/interpreter/util.ts.
- Entry Point: The main script (src/index.ts or src/node.ts) acts as the bridge between parsing source scripts and handing them over to the runtime.

b. Playground (Frontend UI):
- A separate interactive layer found in the playground/ directory.
- Built using Vue (components like App.vue, Settings.vue) and configured with Vite (vite.config.js).
- Provides end users with a visual and interactive environment to write and test AiScript code.

c. Supporting Infrastructure:
- Test Suite: The test directory outlines unit tests for individual language aspects such as literals, types, jump statements, and interpreter behaviors.
- Documentation & Translations: Separate directories that provide user and developer documentation.
- Build and Deployment Scripts: Located in scripts/ (e.g., start.mjs, parse.mjs, check-release.mjs) to automate tasks related to building, releasing, and maintaining the project.
- CI/CD Workflows: GitHub workflows ensure that tests, linting, publishing, and deployment automation are maintained.

##### Relationships and Data Flow
1. Source Code Input → Parser (Scanner → Token Streams → Syntax Analysis with Plugin Validations) → Abstract Syntax Tree (AST).
2. AST → Interpreter (using control flow, scope management, and standard library) → Executed Output in the secure sandbox environment.
3. The playground component interacts with the core engine by sending script input to this processing pipeline and receiving execution results to display.
4. Test and documentation pipelines are peripheral but connect to both the core engine and playground for validating and documenting behavior.

##### Architectural Patterns and Design Principles
- Modular Design: Separate directories for parser and interpreter indicate separation of concerns.
- Plugin Architecture: Custom validations and extendable processing in the parser facilitate specialization and future extensibility.
- Secure Sandbox Execution: Emphasized in the README, showing attention to runtime security.

##### Elements
- Clearly labeled components: Parser, Interpreter, Playground UI, Testing Suite, Documentation/CI Infrastructure.
- Process flow from source to scanning → tokenization → syntax analysis → AST → interpreter execution.
- Communication between playground and core engine.
- Feedback loops (such as tests feeding back into development).
- Core components (e.g., use rectangles for parser/interpreter modules).
- Annotations indicating key technologies (JavaScript, Vue, Vite, Node.js) and design patterns (plugin system, modular design, sandboxing).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Language Engine"
        subgraph "Parser"
            SC["Scanner"]:::parser
            CS["Char Stream"]:::parser
            TS["Token Stream"]:::parser
            CSY["Common Syntax"]:::parser
            EXSYN["Expressions Syntax"]:::parser
            STSYN["Statements Syntax"]:::parser
            TLSYN["Toplevel Syntax"]:::parser
            TYSYN["Types Syntax"]:::parser
            VJ["Validate Jump"]:::parser
            VK["Validate Keyword"]:::parser
            VT["Validate Type"]:::parser
            PUTIL["Parser Utils"]:::parser
            TDEF["Token Definitions"]:::parser
            VIS["Visitor Pattern"]:::parser
        end
        subgraph "AST Generation"
            AST["AST"]:::core
        end
        subgraph "Interpreter"
            CTRL["Control"]:::interpreter
            STD["Std Library"]:::interpreter
            SCOPE["Scope Management"]:::interpreter
            VAR["Variable Handling"]:::interpreter
            PPROP["Primitive Props"]:::interpreter
            REF["Reference"]:::interpreter
            IUTIL["Interpreter Utils"]:::interpreter
            IVALUE["Interpreter Value"]:::interpreter
            IENTRY["Interpreter Entry"]:::interpreter
        end
    end

    subgraph "Entry Point"
        MAIN["Main Script"]:::entry
        NODE["Node Script"]:::entry
    end

    subgraph "Playground UI"
        APP["App.vue"]:::playground
        SET["Settings.vue"]:::playground
        MAINJS["Main.js"]:::playground
        INDEXHTML["Index.html"]:::playground
        VCONFIG["Vite Config"]:::playground
    end

    subgraph "Supporting Infrastructure"
        TEST["Test Suite"]:::support
        DOCS["Documentation"]:::support
        TRANS["Translations"]:::support
        BUILDS["Build Scripts"]:::support
        CI["CI/CD Workflows"]:::support
    end

    USCRIP["User Script Input"]:::user
    OUTPUT["Execution Output"]:::output

    %% Data Flow Connections
    MAIN --> USCRIP
    NODE --> USCRIP
    USCRIP --> SC
    SC --> CS
    SC --> TS
    CS --> CSY
    TS --> CSY
    CSY --> EXSYN
    EXSYN --> STSYN
    STSYN --> TLSYN
    TLSYN --> TYSYN
    TYSYN --> AST
    CSY --> VJ
    CSY --> VK
    CSY --> VT
    CSY --> PUTIL
    CSY --> TDEF
    AST --> VIS
    AST --> CTRL
    CTRL --> STD
    STD --> SCOPE
    SCOPE --> VAR
    VAR --> PPROP
    PPROP --> REF
    REF --> IUTIL
    IUTIL --> IVALUE
    IVALUE --> IENTRY
    IENTRY --> OUTPUT

    %% Playground Interactions
    MAINJS --- USCRIP
    INDEXHTML --- OUTPUT
    APP --- USCRIP
    SET --- USCRIP

    %% Supporting Infrastructure Connections
    TEST --- SC
    TEST --- CTRL
    DOCS --- AST
    TRANS --- AST
    BUILDS --- MAIN
    CI --- MAIN

    %% Click Events
    click SC "https://github.com/syuilo/aiscript/blob/master/src/parser/scanner.ts"
    click CS "https://github.com/syuilo/aiscript/blob/master/src/parser/streams/char-stream.ts"
    click TS "https://github.com/syuilo/aiscript/blob/master/src/parser/streams/token-stream.ts"
    click CSY "https://github.com/syuilo/aiscript/blob/master/src/parser/syntaxes/common.ts"
    click EXSYN "https://github.com/syuilo/aiscript/blob/master/src/parser/syntaxes/expressions.ts"
    click STSYN "https://github.com/syuilo/aiscript/blob/master/src/parser/syntaxes/statements.ts"
    click TLSYN "https://github.com/syuilo/aiscript/blob/master/src/parser/syntaxes/toplevel.ts"
    click TYSYN "https://github.com/syuilo/aiscript/blob/master/src/parser/syntaxes/types.ts"
    click VJ "https://github.com/syuilo/aiscript/blob/master/src/parser/plugins/validate-jump-statements.ts"
    click VK "https://github.com/syuilo/aiscript/blob/master/src/parser/plugins/validate-keyword.ts"
    click VT "https://github.com/syuilo/aiscript/blob/master/src/parser/plugins/validate-type.ts"
    click PUTIL "https://github.com/syuilo/aiscript/blob/master/src/parser/utils.ts"
    click TDEF "https://github.com/syuilo/aiscript/blob/master/src/parser/token.ts"
    click VIS "https://github.com/syuilo/aiscript/blob/master/src/parser/visit.ts"
    
    click CTRL "https://github.com/syuilo/aiscript/blob/master/src/interpreter/control.ts"
    click STD "https://github.com/syuilo/aiscript/blob/master/src/interpreter/lib/std.ts"
    click SCOPE "https://github.com/syuilo/aiscript/blob/master/src/interpreter/scope.ts"
    click VAR "https://github.com/syuilo/aiscript/blob/master/src/interpreter/variable.ts"
    click PPROP "https://github.com/syuilo/aiscript/blob/master/src/interpreter/primitive-props.ts"
    click REF "https://github.com/syuilo/aiscript/blob/master/src/interpreter/reference.ts"
    click IUTIL "https://github.com/syuilo/aiscript/blob/master/src/interpreter/util.ts"
    click IVALUE "https://github.com/syuilo/aiscript/blob/master/src/interpreter/value.ts"
    click IENTRY "https://github.com/syuilo/aiscript/blob/master/src/interpreter/index.ts"
    
    click MAIN "https://github.com/syuilo/aiscript/blob/master/src/index.ts"
    click NODE "https://github.com/syuilo/aiscript/blob/master/src/node.ts"
    
    click APP "https://github.com/syuilo/aiscript/blob/master/playground/src/App.vue"
    click SET "https://github.com/syuilo/aiscript/blob/master/playground/src/Settings.vue"
    click MAINJS "https://github.com/syuilo/aiscript/blob/master/playground/src/main.js"
    click INDEXHTML "https://github.com/syuilo/aiscript/blob/master/playground/index.html"
    click VCONFIG "https://github.com/syuilo/aiscript/blob/master/playground/vite.config.js"
    
    click TEST "https://github.com/syuilo/aiscript/tree/master/test"
    click DOCS "https://github.com/syuilo/aiscript/tree/master/docs"
    click TRANS "https://github.com/syuilo/aiscript/tree/master/translations"
    click BUILDS "https://github.com/syuilo/aiscript/tree/master/scripts"
    click CI "https://github.com/syuilo/aiscript/tree/master/.github/workflows"

    %% Styles
    classDef parser fill:#ccf,stroke:#333,stroke-width:2px;
    classDef interpreter fill:#cfc,stroke:#333,stroke-width:2px;
    classDef entry fill:#fc9,stroke:#333,stroke-width:2px;
    classDef playground fill:#cff,stroke:#333,stroke-width:2px;
    classDef support fill:#ffc,stroke:#333,stroke-width:2px;
    classDef user fill:#f9c,stroke:#333,stroke-width:2px;
    classDef output fill:#9fc,stroke:#333,stroke-width:2px;
    classDef core fill:#e0e0ff,stroke:#333,stroke-width:2px;
```
