# kzhsw/xatlas-wasi architecture

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

## Overview

##### Project Type and Purpose
- This project is a WebAssembly (Wasm) module build of the xatlas C API (used for texture atlas generation) that is compiled with the wasi-sdk. It also includes TypeScript bindings that serve as a glue layer to call into the Wasm module from JavaScript environments.
- The README clearly states that this is a “raw build of xatlas C api” with a TypeScript binding. There’s no high-level API yet, so the focus is on exposing low-level functionality through Wasm.

##### Analyzing the File Structure
- Top-Level Files and Folders:
- .github/workflows: Contains CI/CD configuration (e.g., makefile.yml, npm-publish.yml) to automate builds and possibly tests.
- Makefile: A build script likely targeting the conversion of the C code into Wasm with the wasi-sdk.
- package.json and tsconfig files: Define the Node/TypeScript build environment.
- index.ts: The primary TypeScript binding file that demonstrates how to instantiate and interact with the Wasm module.
- copy_uv.c: A C source file, most likely implementing utility functionality (for copying UV data) that is part of the low-level API.
- xatlas and the generated files (xatlas.wasm, xatlas-dbg.wasm as listed in the README): Represent the outcomes of the build process from the C source.

##### Key Components
A. Build & CI Pipeline:
- Workflows (.github/workflows) and Makefile indicating the build automation using the wasi-sdk.
B. C Source Layer (Native Code):
- Component representing the xatlas C API (including files like copy_uv.c) compiled with wasi-sdk. This produces two Wasm binaries: an optimized release version (xatlas.wasm) and a debug build (xatlas-dbg.wasm).
C. WebAssembly Module:
- The compiled Wasm module that encapsulates the xatlas functionality. Note that it exposes memory and functions (like xatlasCreate, xatlasAddMesh, etc.) to be consumed by external code.
D. TypeScript Binding/Integration Layer:
- index.ts (and related TypeScript code) which instantiates the Wasm module at runtime, provides the glue (e.g., context management, memory access utilities) for calling the C API functions, and exposes the interface to application-level JavaScript/TypeScript code.
E. Runtime Environment:
- The example provided in the README shows how the Wasm module is instantiated via WebAssembly.instantiateStreaming. Include the JavaScript “env” object that supplies helper functions (logging, progress reporting) and a stubbed WASI environment for system calls.

##### Relationships and Interactions
- The build system (Makefile, CI workflows) compiles the native C code using the wasi-sdk into the Wasm binaries.
- The TypeScript binding layer (index.ts) loads the Wasm module (either xatlas.wasm or xatlas-dbg.wasm) into a WebAssembly instance.
- The TypeScript code interacts with the exported functions (e.g., xatlasCreate, xatlasMeshDeclInit, xatlasAddMesh) to carry out mesh and UV processing.
- The “env” and “wasi_snapshot_preview1” objects provided in the imports during instantiation indicate how external dependencies (such as logging and filesystem-stub functions) are injected into the module.
- There is also a clear data flow where the TypeScript code allocates memory buffers, writes mesh data into Wasm memory, and later reads back processed data (e.g., indices, UVs).

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project divides responsibilities between native code (C) and the runtime binding (TypeScript).
- CI/CD Integration: Include an element showing how automated workflows (via GitHub Actions) tie into the build process.
- WebAssembly and WASI: Emphasize the adherence to WebAssembly standards and the use of WASI for system-level operations.

##### Instructing the Principal Software Engineer
– Code/build components (e.g., rectangles for CI/Build tools and source code)
– Integration layer (e.g., a rounded rectangle for TypeScript bindings)
- External interfaces (like the “env” object during Wasm instantiation) to show how the module handles logging and progress callbacks.
- Low-level data flow: from data input in the TypeScript code, memory allocation in the Wasm module, to reading back results.

## Diagram (Mermaid)

```mermaid
graph TD
    %% CI Pipeline/Build System
    subgraph "CI Pipeline/Build System"
        CI1["Makefile"]:::ci
        CI2[".github/workflows/makefile.yml"]:::ci
        CI3[".github/workflows/npm-publish.yml"]:::ci
    end

    %% C Source Layer
    subgraph "C Source Layer (xatlas C API & copy_uv.c)"
        CS1["copy_uv.c"]:::c_source
        CS2["xatlas C API Directory"]:::c_source
    end

    %% WebAssembly Module
    subgraph "WebAssembly Module"
        WASM1["Wasm Build Artifacts (xatlas.wasm & xatlas-dbg.wasm)"]:::wasm
    end

    %% TypeScript Binding
    subgraph "TypeScript Binding"
        TS1["index.ts"]:::ts
    end

    %% Runtime Environment
    subgraph "Runtime Environment"
        RE1["Runtime Environment (env + WASI)"]:::runtime
    end

    %% Build Flow
    CI1 -->|"triggers_build"| CS1
    CI2 -->|"triggers_build"| CS1
    CI3 -->|"triggers_build"| CS1

    CS2 -->|"compiled_to"| WASM1

    %% Runtime Interaction
    TS1 -->|"loads&interacts"| WASM1
    WASM1 -->|"returns_data"| TS1
    RE1 -->|"supplies_env"| TS1

    %% Click Events for CI Pipeline/Build System
    click CI1 "https://github.com/kzhsw/xatlas-wasi/tree/main/Makefile"
    click CI2 "https://github.com/kzhsw/xatlas-wasi/blob/main/.github/workflows/makefile.yml"
    click CI3 "https://github.com/kzhsw/xatlas-wasi/blob/main/.github/workflows/npm-publish.yml"

    %% Click Events for C Source Layer
    click CS1 "https://github.com/kzhsw/xatlas-wasi/blob/main/copy_uv.c"
    click CS2 "https://github.com/kzhsw/xatlas-wasi/tree/main/xatlas"

    %% Click Event for WebAssembly Module
    click WASM1 "https://github.com/kzhsw/xatlas-wasi/tree/main/xatlas"

    %% Click Event for TypeScript Binding
    click TS1 "https://github.com/kzhsw/xatlas-wasi/blob/main/index.ts"

    %% Styles
    classDef ci fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef c_source fill:#aed6f1,stroke:#2874a6,stroke-width:2px;
    classDef wasm fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef ts fill:#fad7a0,stroke:#e67e22,stroke-width:2px;
    classDef runtime fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
```
