# snowfoxsh/aplang architecture

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

- Interactive diagram: https://gitdiagram.com/snowfoxsh/aplang
- Repository: https://github.com/snowfoxsh/aplang

## Overview

##### Main Components
- Language Core – This includes modules under the “src” directory:
- Lexer: Found in src/lexer/ (lexer.rs, token.rs, tests.rs) which tokenizes source code.
- Parser: Located in src/parser/ (parser.rs, ast.rs) that builds an AST from the token stream.
- Interpreter: Under src/interpreter/ (interpreter.rs, env.rs, procedure.rs, value.rs) that processes the AST.
- Standard Library: In src/standard_library/ providing built-in functions, file system, math, IO, robot, and other educational utilities.
- Core Logic: Additional modules like src/aplang.rs, src/arguments.rs, src/output.rs which help manage language execution.

- Execution Front-Ends:
- CLI and Launcher: The “launcher” folder with its own Cargo.toml and main.rs provides the command-line interface in a desktop context.
- WASM Support: The file src/wasm.rs indicates integration with WebAssembly for running the language in a browser-based playground.

- Example Programs:
- The “examples.ap” directory contains sample .ap (ApLang) scripts (like fib.ap, bubblesort.ap, etc.) that illustrate usage and serve as tests or demos.

- Build, Configuration, and CI:
- Cargo files (Cargo.toml, Cargo.lock) show dependency management.
- CI scripts in the ci folder and GitHub workflows help with packaging (MSIX packages) and testing.

##### Relationships & Data Flow
- Data Flow Pipeline:
- Source (AP program from examples or user input) → Lexer (src/lexer/) → Parser (src/parser/) → AST → Interpreter (src/interpreter/) → Execution (utilizing the Standard Library modules).
- Environment and Extensions:
- The Standard Library modules extend core functionality.
- WASM and CLI “launcher” act as distinct front-ends that call into the same interpreter/core.
- Integration Points:
- Configuration files and CI integrations show how changes are deployed and tested.

##### Architectural Patterns & Design Principles
- Layered Pipeline Architecture:
- A sequential processing pipeline: Lexing → Parsing → Interpretation.
- Separation of Concerns:
- Core runtime logic is decoupled from input methods (CLI vs. WASM), making the language versatile.
- Modularity:
- The standard library and AST modules emphasize modularity for easier extension and testing.

##### Relevant Technologies and Tools
- Rust is the primary technology (as seen by Cargo configuration).
- GitHub Actions for CI/CD in .github/workflows.
- WASM integration for client-side execution.
- Packaging components (MSIX) via scripts in ci.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Execution Front-Ends Subgraph
    subgraph "Execution Front-Ends"
        CLI["CLI/Launcher"]:::frontend
        WASM["WASM Support"]:::frontend
        EXAMPLES["Example Programs"]:::external
    end

    %% Language Core Pipeline Subgraph
    subgraph "Language Core Pipeline"
        LEX["Lexer"]:::core
        PAR["Parser"]:::core
        INT["Interpreter"]:::core
        STD["Standard Library"]:::core
        CORE["Core Logic Modules"]:::core
    end

    %% Build/Configuration & CI Subgraph
    subgraph "Build/Configuration & CI"
        CARGO["Cargo Configuration"]:::config
        CI_NODE["CI/CD & Packaging Scripts"]:::config
    end

    %% Data flow from Execution Front-Ends to Language Core Pipeline
    CLI -->|"sourceCode"| LEX
    WASM -->|"sourceCode"| LEX
    EXAMPLES -->|"sampleProgram"| LEX

    %% Language Core Processing Pipeline
    LEX -->|"tokenStream"| PAR
    PAR -->|"AST"| INT
    INT -->|"execContext"| STD
    CORE -.->|"controlSupport"| INT

    %% Build/Configuration integration with CLI front-end (deployment/build)
    CARGO ---|"build"| CLI
    CI_NODE ---|"deploy"| CLI

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef frontend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef config fill:#FFFACD,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;

    %% Click Events
    click LEX "https://github.com/snowfoxsh/aplang/tree/master/src/lexer/"
    click PAR "https://github.com/snowfoxsh/aplang/tree/master/src/parser/"
    click INT "https://github.com/snowfoxsh/aplang/tree/master/src/interpreter/"
    click STD "https://github.com/snowfoxsh/aplang/tree/master/src/standard_library/"
    click CORE "https://github.com/snowfoxsh/aplang/blob/master/src/aplang.rs"
    click CLI "https://github.com/snowfoxsh/aplang/tree/master/launcher/"
    click WASM "https://github.com/snowfoxsh/aplang/blob/master/src/wasm.rs"
    click EXAMPLES "https://github.com/snowfoxsh/aplang/tree/master/examples.ap/"
    click CARGO "https://github.com/snowfoxsh/aplang/blob/master/Cargo.toml"
    click CI_NODE "https://github.com/snowfoxsh/aplang/tree/master/.github/workflows/"
```
