# ashitomw/scripto architecture

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

- Interactive diagram: https://gitdiagram.com/ashitomw/scripto
- Repository: https://github.com/ashitomw/scripto

## Overview

##### Project Type and Purpose
- Scripto Lang is an interpreted toy programming language implemented in TypeScript.
- It provides a simple CLI REPL, a classic compile-and-interpret pipeline (lexer → parser → AST → interpreter), and basic runtime types (`number`, `null`).

##### Top-Level Modules and Components
- **main.ts (REPL entry point)**: Handles user I/O.
- **core/**
- lexer.ts – Converts input strings into tokens.
- parser.ts – Builds an AST from tokens.
- ast.ts – Defines AST node structures.
- utils.ts – Shared helper functions (e.g., token utilities, error formatting).
- **runtime/**
- interpreter.ts – Walks the AST and produces runtime values.
- values.ts – Defines the runtime value types and type-checking logic.
- **Config & Build**
- tsconfig.json, package.json – TypeScript/Node build settings (not in the execution pipeline but can be shown as a side note).

##### Key Architectural Pattern
- A linear “compiler pipeline” (lexer → parser → AST → interpreter) inside a single process.
- A REPL wrapper around that pipeline orchestrates input/output.
- All modules run in the Node.js runtime with ES module loading.

##### Main Components & Data Flows
A. REPL Interface (main.ts)
B. Lexer Module (core/lexer.ts)
C. Parser Module (core/parser.ts)
D. AST Definitions (core/ast.ts)
E. Utilities (core/utils.ts) – support both the lexer and parser
F. Interpreter (runtime/interpreter.ts)
G. Runtime Values (runtime/values.ts)
H. Console/Stdout

1. User enters code → REPL Interface
2. REPL passes raw input → Lexer
3. Lexer outputs Token Stream → Parser
4. Parser references AST Definitions → produces AST
5. Parser/Interpreter may call Utils (error handling, helper routines)
6. AST → Interpreter
7. Interpreter references Runtime Values → evaluates, returns a Value
8. Value → REPL Interface → Console output

##### Technologies and Files
- “Lexer (core/lexer.ts): tokenize numbers, operators, parentheses”
- “Parser (core/parser.ts): recursive descent with precedence”
- “Interpreter (runtime/interpreter.ts): AST walker, operation implementations”
- In the environment container, list “TypeScript, ES modules, ts-node/tsx, Node.js”.

##### Essential Details
- Where errors/exceptions could bubble up (e.g., lexical errors, parse errors).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main runtime container
    subgraph "Node.js Runtime (TypeScript, ES modules)" 
        direction TB
        REPL["REPL Interface\n(main.ts)"]:::repl
        Lexer["Lexer Module\n(core/lexer.ts)"]:::compiler
        Parser["Parser Module\n(core/parser.ts)"]:::compiler
        AST["AST Definitions\n(core/ast.ts)"]:::compiler
        Interpreter["Interpreter\n(runtime/interpreter.ts)"]:::runtime
    end

    %% Output
    Console["Console / Stdout"]:::repl

    %% Side modules
    subgraph "Utility Modules"
        direction TB
        Utils["Utilities\n(core/utils.ts)"]:::util
    end

    subgraph "Runtime Types"
        direction TB
        Values["Runtime Values\n(runtime/values.ts)"]:::util
    end

    %% Config files
    subgraph "Config & Build Settings"
        direction TB
        TSConfig["tsconfig.json"]:::config
        Package["package.json"]:::config
    end

    %% Data flow arrows
    REPL -->|1 raw input| Lexer
    Lexer -->|2 token stream| Parser
    Parser -->|3 uses AST definitions| AST
    Parser -->|4 produces AST| Interpreter
    AST -.->|reference| Parser
    Utils -.->|helpers| Lexer
    Utils -.->|helpers| Parser
    Values -.->|type info| Interpreter
    Interpreter -->|5 runtime value| REPL
    REPL -->|6 output| Console
    Console -->|7 next prompt| REPL

    %% Click Events
    click REPL "https://github.com/ashitomw/scripto/blob/main/main.ts"
    click Lexer "https://github.com/ashitomw/scripto/blob/main/core/lexer.ts"
    click Parser "https://github.com/ashitomw/scripto/blob/main/core/parser.ts"
    click AST "https://github.com/ashitomw/scripto/blob/main/core/ast.ts"
    click Utils "https://github.com/ashitomw/scripto/blob/main/core/utils.ts"
    click Interpreter "https://github.com/ashitomw/scripto/blob/main/runtime/interpreter.ts"
    click Values "https://github.com/ashitomw/scripto/blob/main/runtime/values.ts"
    click TSConfig "https://github.com/ashitomw/scripto/blob/main/tsconfig.json"
    click Package "https://github.com/ashitomw/scripto/blob/main/package.json"

    %% Styles
    classDef repl fill:#FFD54F,stroke:#333,stroke-width:1px
    classDef compiler fill:#90CAF9,stroke:#333,stroke-width:1px
    classDef runtime fill:#A5D6A7,stroke:#333,stroke-width:1px
    classDef util fill:#E0E0E0,stroke-dasharray: 5 5,stroke:#333
    classDef config fill:#EF9A9A,stroke:#333,stroke-width:1px
```
