# blessnetwork/sdk-ts architecture

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

- Interactive diagram: https://gitdiagram.com/blessnetwork/sdk-ts
- Repository: https://github.com/blessnetwork/sdk-ts

## Overview

##### Project type and purpose
- This is a TypeScript‐based SDK plus CLI tool (`@blockless/sdk-ts`) that compiles user JS/TS code into a WebAssembly module targeting the BLESS Javy WASM Engine.
- It provides polyfills for missing Node/Web APIs (crypto, http/fetch, stdin) and dynamically bundles only the selected “plugins” (full, llm, crypto, fetch).

##### File structure
- Top level:
- .github/workflows: CI for publishing
- bundler/: CLI implementation (`bundler/index.ts`) for building and managing Javy/plugins
- lib/: core SDK code and polyfills (`entry.ts`, `index.ts`, `polyfill/crypto.ts`, `stdin.ts`, `web.ts`)
- examples/: sample user projects (crypto, env, fetch, llm, stdin)
- types/: TypeScript declarations
- package.json, tsconfig.json, biome.json: build/config files
- Patterns & configuration:
- CLI entry point in bundler
- SDK entryMain and InputProps abstractions in lib/entry.ts
- Plugin feature flags passed to the bundler CLI
- Output artifacts: `.wasm` modules in user’s outDirectory

##### README for technical stack & commands
- Build command: `bls-sdk-ts build ./index.ts -o <outDir> -f <outFile>`
- Example of building: `node ./dist/bundler build ./examples/llm/index.ts … --features llm`
- Uninstall/update manages Javy engine and plugins
- Supported SDK APIs: JSON, HTTP/fetch, crypto, stdin

a. Main components
- User Project / Source Code (examples or any npm project importing `@blockless/sdk-ts`)
- SDK Library (`lib/*`): entryMain, polyfills, type definitions
- Bundler CLI (`bundler/index.ts`)
- Javy WASM Engine & Plugins (crypto, fetch, llm, full)
- Host Environment for WASM (network, cryptography, stdin/stdout)

b. Relationships & data flow
1. Developer writes TS code that imports `@blockless/sdk-ts` → passes business logic into `entryMain`.
2. Bundler CLI runs under Node, invokes Javy CLI to compile TS → WASM, injecting only requested plugins.
3. Output `.wasm` is deployed or executed via the Javy Engine.
4. At runtime, the WASM module uses polyfills to talk to the engine’s host functions (e.g., crypto calls go to the engine’s crypto plugin).
5. InputProps JSON is fed in via stdin or Javy API; user callback executes; output JSON is returned.

c. Architectural patterns & design principles
- Plugin Architecture: feature flags selectively include / exclude host plugins.
- Layered Design:
– Build‐time (Node CLI, TypeScript → WASM)
– SDK Core (entry point + polyfills)
– Host Integration (Javy Engine + plugins)
- Separation of Concerns: User code vs. SDK vs. WASM runtime vs. host services

d. Key technologies & libraries
- TypeScript, Node.js for build tooling
- Javy WASM engine for running compiled modules
- Ethers AbiCoder in examples
- npm ecosystem for module resolution
- Custom polyfills in `lib/polyfill`

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Layer
    subgraph "Developer / Project" 
        classDef developer fill:#f9f,stroke:#333,stroke-width:1px;
        subgraph "Examples / Source Code"
            CryptoEx["crypto/index.ts"]:::developer
            EnvEx["env/index.ts"]:::developer
            FetchEx["fetch/index.ts"]:::developer
            LLMLEx["llm/index.ts"]:::developer
            StdinEx["stdin/index.ts"]:::developer
        end
        UserCode["User TS Code"]:::developer
    end

    %% Build & Packaging Layer
    subgraph "Build & Packaging" 
        classDef build fill:#9cf,stroke:#333,stroke-width:1px;
        CLI["Bundler CLI<br/>(bundler/index.ts)"]:::build
        TSConfig["TypeScript Compiler<br/>(tsconfig.json)"]:::build
        Biome["Lint/Format Config<br/>(biome.json)"]:::build
        Package["package.json"]:::build
        JavyCLI["Javy CLI<br/>(WASM Build)"]:::build
        WASMOutput[".wasm Output Module"]:::build
    end

    %% Runtime Layer
    subgraph "Runtime Layer"
        classDef runtime fill:#cfc,stroke:#333,stroke-width:1px;
        WASMMod["WASM Module"]:::runtime
        SDKCore["SDK Core<br/>(lib/index.ts)"]:::runtime
        Entry["entryMain & InputProps<br/>(lib/entry.ts)"]:::runtime

        subgraph "SDK Polyfills"
            classDef polyfill fill:#cff,stroke:#333,stroke-width:1px;
            CryptoPF["crypto.ts"]:::polyfill
            StdinPF["stdin.ts"]:::polyfill
            FetchPF["web.ts"]:::polyfill
        end

        subgraph "Host Environment / Javy Engine"
            classDef host fill:#fc9,stroke:#333,stroke-width:1px;
            Engine["Javy WASM Engine"]:::host
            CryptoPlugin["Crypto Plugin"]:::host
            FetchPlugin["Fetch Plugin"]:::host
            LLMPlugin["LLM Plugin"]:::host
            FullPlugin["Full Plugin"]:::host
        end
    end

    %% Connections: Developer -> Build
    CryptoEx -->|imports SDK| UserCode
    EnvEx --> UserCode
    FetchEx --> UserCode
    LLMLEx --> UserCode
    StdinEx --> UserCode
    UserCode -->|bls-sdk-ts build| CLI
    CLI -->|reads config| TSConfig
    CLI -->|loads flags| Package
    CLI -->|lints| Biome
    CLI -->|"invokes"| JavyCLI
    JavyCLI -->|"outputs"| WASMOutput

    %% Build -> Runtime
    WASMOutput --> WASMMod

    %% Runtime internal flow
    WASMMod --> SDKCore
    SDKCore --> Entry
    Entry --> CryptoPF
    Entry --> StdinPF
    Entry --> FetchPF
    CryptoPF --> CryptoPlugin
    FetchPF --> FetchPlugin
    Entry --> Engine
    Engine --> LLMPlugin
    Engine --> FullPlugin
    Engine -->|"stdin/stdout"| StdinPF

    %% InputProps Data Flow
    Engine -->|feeds InputProps JSON| Entry
    Entry -->|calls User Code| WASMMod
    WASMMod -->|returns JSON Output| Engine

    %% Click Events
    click CryptoEx "https://github.com/blessnetwork/sdk-ts/blob/main/examples/crypto/index.ts"
    click EnvEx "https://github.com/blessnetwork/sdk-ts/blob/main/examples/env/index.ts"
    click FetchEx "https://github.com/blessnetwork/sdk-ts/blob/main/examples/fetch/index.ts"
    click LLMLEx "https://github.com/blessnetwork/sdk-ts/blob/main/examples/llm/index.ts"
    click StdinEx "https://github.com/blessnetwork/sdk-ts/blob/main/examples/stdin/index.ts"
    click CLI "https://github.com/blessnetwork/sdk-ts/blob/main/bundler/index.ts"
    click TSConfig "https://github.com/blessnetwork/sdk-ts/blob/main/tsconfig.json"
    click Biome "https://github.com/blessnetwork/sdk-ts/blob/main/biome.json"
    click Package "https://github.com/blessnetwork/sdk-ts/blob/main/package.json"
    click SDKCore "https://github.com/blessnetwork/sdk-ts/blob/main/lib/index.ts"
    click Entry "https://github.com/blessnetwork/sdk-ts/blob/main/lib/entry.ts"
    click CryptoPF "https://github.com/blessnetwork/sdk-ts/blob/main/lib/polyfill/crypto.ts"
    click StdinPF "https://github.com/blessnetwork/sdk-ts/blob/main/lib/stdin.ts"
    click FetchPF "https://github.com/blessnetwork/sdk-ts/blob/main/lib/web.ts"

    %% Legend
    subgraph Legend
        DEV["Developer Layer"]:::developer
        BLD["Build & Packaging"]:::build
        RNT["Runtime Layer"]:::runtime
        PLY["Plugin/Polyfill"]:::polyfill
        HST["Host/Engine"]:::host
    end

    class DEV,BLD,RNT,PLY,HST title;
```
