# software-mansion/typegpu architecture

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

- Interactive diagram: https://gitdiagram.com/software-mansion/typegpu
- Repository: https://github.com/software-mansion/typegpu

## Overview

Based on our analysis of the file tree and README, the project is a monorepo hosting a TypeScript library called TypeGPU that enhances the WebGPU API with a type‐safe, declarative approach. In addition to the core library (in packages/typegpu), the repository contains several related packages (such as unplugin-typegpu, tgpu-gen, tgpu-jit, tinyest, tinyest-for-wgsl, and tgpu-wgsl-parser) that provide build plugins, automatic code generation, JIT transpilation, parsing, and shared type definitions. There is also an “apps” folder that hosts the TypeGPU documentation website with examples and benchmarks.

##### Overall Structure
- Within “Packages”, list and group the individual modules:
- Core Library (packages/typegpu): This is the heart of the repository, implementing the type-safe WebGPU bindings and resource management.
- Build Plugins (packages/unplugin-typegpu): These are integrations for different build tools (Babel, Rollup, Vite, Webpack, etc.) to support TypeGPU.
- CLI/Development Tools (packages/tgpu-dev-cli): Contains utilities used by developers for local development.
- Code Generation and JIT (packages/tgpu-gen and packages/tgpu-jit): Tools for automatic TypeGPU code generation as well as JIT transpiling.
- Parsing and Transformation (packages/tgpu-wgsl-parser, packages/tinyest, packages/tinyest-for-wgsl): Components for parsing WGSL code and transforming JavaScript to an intermediate “tinyest” representation.
- “Apps” includes the documentation and examples site (apps/typegpu-docs), which ties into the core library by demonstrating usage and running benchmarks.

##### Component Relationships and Data Flow
- That the build plugins (unplugin-typegpu) and CLI tools (tgpu-gen, tgpu-dev-cli) are utility layers built on top of, or interacting with, the core TypeGPU functionality.
- Parsing and transformation packages as pre-processing or compilation support components that feed into the main toolchain. For example, the WGSL parser and the tinyest conversion libraries are used to prepare code for the GPU pipelines.
- Dependencies between packages. For instance, the core library likely calls into various utility components (data handling, pipelines, slot management, etc.) and the CLI/JIT modules depend on the core library to perform their tasks.

##### Architectural Patterns and Design Principles
- Modular nature—the monorepo is constructed with clearly defined modules following separation of concerns.
- There is a layered architecture where lower-level modules (e.g., data and pipeline creation in the core) are consumed by higher-level developer tools (CLI, JIT, build plugins).
- The design supports both compile-time (via tgpu-gen code generation) and runtime (via tgpu-jit transpiling) enhancements of GPU code, making it important to capture both pipeline dependency and usage flows.
- Declarative and type-safe design principles as mentioned in the README, visually grouping components that participate in those domains (e.g., core functions, shader generation, and pipeline setup).

##### Technologies and Key Elements
- Documentation app’s use of Astro (per the astro.config.mjs file) along with its use of React components (seen from the .tsx files) for interactive examples.
- Where appropriate, include notes about WebGPU and WGSL since these are fundamental to the library’s operation.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Monorepo"
        subgraph "Packages"
            A["Core Library (packages/typegpu)"]
            B["Build Plugins (packages/unplugin-typegpu)"]
            C(("CLI/Development Tools (packages/tgpu-dev-cli)"))
            D(("Code Generation (packages/tgpu-gen)"))
            E(("JIT Transpiler (packages/tgpu-jit)"))
            F(("WGSL Parsing (packages/tgpu-wgsl-parser)"))
            G(("Tinyest (packages/tinyest)"))
            H(("Tinyest for WGSL (packages/tinyest-for-wgsl)"))
            I["TypeGPU Color (packages/typegpu-color)"]
            J["TypeGPU Noise (packages/typegpu-noise)"]
        end
        subgraph "Apps"
            K(["Documentation App (apps/typegpu-docs)"])
        end
    end

    %% Relationships
    K -->|"consumes"| A
    B -->|"buildsOn"| A
    C -->|"dependsOn"| A
    D -->|"generatesFor"| A
    E -->|"transpilesFor"| A
    F -->|"preprocesses"| D
    G -->|"transforms"| D
    H -->|"transforms"| D
    I -->|"supports"| A
    J -->|"supports"| A

    %% Click Events
    click A "https://github.com/software-mansion/typegpu/tree/main/packages/typegpu"
    click B "https://github.com/software-mansion/typegpu/tree/main/packages/unplugin-typegpu"
    click C "https://github.com/software-mansion/typegpu/tree/main/packages/tgpu-dev-cli"
    click D "https://github.com/software-mansion/typegpu/tree/main/packages/tgpu-gen"
    click E "https://github.com/software-mansion/typegpu/tree/main/packages/tgpu-jit"
    click F "https://github.com/software-mansion/typegpu/tree/main/packages/tgpu-wgsl-parser"
    click G "https://github.com/software-mansion/typegpu/tree/main/packages/tinyest"
    click H "https://github.com/software-mansion/typegpu/tree/main/packages/tinyest-for-wgsl"
    click I "https://github.com/software-mansion/typegpu/tree/main/packages/typegpu-color"
    click J "https://github.com/software-mansion/typegpu/tree/main/packages/typegpu-noise"
    click K "https://github.com/software-mansion/typegpu/tree/main/apps/typegpu-docs"

    %% Styles
    classDef core fill:#f7d4d4,stroke:#cc0000,stroke-width:2px;
    classDef plugin fill:#d4e8fc,stroke:#0055aa,stroke-width:2px;
    classDef tool fill:#d4fcd8,stroke:#008800,stroke-width:2px;
    classDef transformation fill:#fcfdd4,stroke:#aaaa00,stroke-width:2px;
    classDef utility fill:#e8d4fc,stroke:#6600cc,stroke-width:2px;
    classDef app fill:#d4fcfd,stroke:#00aaaa,stroke-width:2px;

    class A core;
    class B plugin;
    class C tool;
    class D tool;
    class E tool;
    class F transformation;
    class G transformation;
    class H transformation;
    class I utility;
    class J utility;
    class K app;
```
