# sp5555/websplat architecture

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

- Interactive diagram: https://gitdiagram.com/sp5555/websplat
- Repository: https://github.com/sp5555/websplat

## Overview

##### Project type and purpose
- This is a pure-front-end, browser-based 3D scene renderer built on WebGPU and WGSL.
- It loads geometry (PLY files), preprocesses data, sorts elements on the GPU, tiles/meshes them, and finally renders a scene in real time.

##### File structure
- Top-level:
- index.html – entry point, pulls in main.js, CSS, shaders.
- css/ – visual styling.
- shaders/ – WGSL shader modules organized by pipeline stage: render, sort, tile, transform.
- src/ – JS source code, further broken down into logical managers and utilities.
- package.json – metadata (dev dependencies, scripts).

- src/ substructure reveals architectural roles:
- app/app.js – the orchestrator that initializes App, ties subsystems together.
- gui/gui-manager.js & hud/hud-manager.js – UI layers.
- input/input.js – user interaction handling.
- loaders/ply-loader.js – model loading.
- preprocessing/gaussian-precompute.js – CPU-side image/data prep.
- renderer/ – core rendering pipeline:
– camera.js (view/projection)
– mesh-buffer-builder.js (vertex/index buffer construction)
– renderer.js (GPU device setup, command encoding, render pass orchestration)
– wgsl-shader.js (shader compilation and module management)
- utils/ – shared helpers (events, GUI utilities).

##### Insights from README
- No backend; served via a static HTTP server.
- Emphasis on sort (bitonic), NDC manipulation, WebGPU usage.
- Identifies optimization work still pending.

##### Detail
- Break the renderer pipeline into its four shader stages (transform, sort, tile, render).
- Event-emitter links between modules.
- HTML/CSS layer and how GUI/HUD integrate on top of the WebGPU canvas.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Browser Layer
    subgraph "Browser Environment"
        direction TB
        HTML["index.html"]:::doc
        CSS["styles.css"]:::doc
        HTML -->|"includes"| MainJS["main.js"]:::cpu
    end

    %% CPU Side
    subgraph "CPU Modules"
        direction TB
        AppCore["App Core\n(app.js)"]:::cpu
        InputMgr["Input Manager\n(input.js)"]:::cpu
        GUIMgr["GUI Manager\n(gui-manager.js)"]:::cpu
        HUDMgr["HUD Manager\n(hud-manager.js)"]:::cpu
        Loader["PLY Loader\n(ply-loader.js)"]:::cpu
        Preproc["Preprocessor\n(gaussian-precompute.js)"]:::cpu
        Utils["Event Utils\n(event-emitters.js,\nevent.js,\ngu i-utils.js)"]:::cpu
    end

    %% Renderer Pipeline
    subgraph "Renderer Pipeline"
        direction TB
        RendererJS["Renderer\n(renderer.js)"]:::cpu
        Camera["Camera\n(camera.js)"]:::cpu
        MeshBuilder["Mesh Buffer Builder\n(mesh-buffer-builder.js)"]:::cpu
        ShaderMgr["WGSL Shader Manager\n(wgsl-shader.js)"]:::cpu
        GPUDevice["GPU Device & Queue"]:::gpu
        subgraph "Shader Stages"
            direction TB
            Transform["Transform Stage\n(transform.wgsl)"]:::gpu
            Sort["Sort Stage\n(sort-bitonic.wgsl,\nsort-oe-f.wgsl,\nsort-oe.wgsl)"]:::gpu
            Tile["Tile Stage\n(tile.wgsl)"]:::gpu
            RenderStage["Render Stage\n(render.wgsl,\nrender-first-splat.wgsl,\nrender-flat.wgsl,\nrender-outline.wgsl)"]:::gpu
        end
        VertBuf["Vertex Buffer"]:::store
        IndexBuf["Index Buffer"]:::store
        SortBuf["Intermediate Sort Buffer"]:::store
        Canvas["HTMLCanvasElement"]:::output
    end

    %% Dependencies
    HTML -->|bootstraps| AppCore
    MainJS -->|initializes| AppCore
    AppCore -->|initializes| InputMgr
    AppCore -->|initializes| GUIMgr
    AppCore -->|initializes| HUDMgr
    AppCore -->|uses| Utils
    InputMgr -->|emits events| AppCore
    AppCore -->|loads geometry| Loader
    Loader -->|provides PLY data| Preproc
    Preproc -->|uploads| VertBuf
    Preproc -->|uploads| IndexBuf

    AppCore -->|starts render| RendererJS
    RendererJS -->|sets up| GPUDevice
    RendererJS -->|uses| Camera
    RendererJS -->|uses| MeshBuilder
    RendererJS -->|compiles shaders| ShaderMgr
    ShaderMgr -->|provides| Transform
    ShaderMgr -->|provides| Sort
    ShaderMgr -->|provides| Tile
    ShaderMgr -->|provides| RenderStage

    GPUDevice -->|binds| VertBuf
    GPUDevice -->|binds| IndexBuf
    GPUDevice -->|binds| SortBuf
    GPUDevice -->|dispatches| Transform
    Transform -->|writes| VertBuf
    GPUDevice -->|dispatches| Sort
    Sort -->|writes| SortBuf
    GPUDevice -->|dispatches| Tile
    Tile -->|writes| SortBuf
    GPUDevice -->|executes| RenderStage
    RenderStage -->|renders to| Canvas

    %% UI Overlay
    Canvas -->|underlays| GUIMgr
    Canvas -->|underlays| HUDMgr

    %% Metadata
    Package["package.json"]:::meta

    AppCore -->|reads| Package

    %% Click Events
    click HTML "https://github.com/sp5555/websplat/blob/main/index.html"
    click CSS "https://github.com/sp5555/websplat/blob/main/css/styles.css"
    click MainJS "https://github.com/sp5555/websplat/blob/main/src/main.js"
    click AppCore "https://github.com/sp5555/websplat/blob/main/src/app/app.js"
    click GUIMgr "https://github.com/sp5555/websplat/blob/main/src/gui/gui-manager.js"
    click HUDMgr "https://github.com/sp5555/websplat/blob/main/src/hud/hud-manager.js"
    click InputMgr "https://github.com/sp5555/websplat/blob/main/src/input/input.js"
    click Loader "https://github.com/sp5555/websplat/blob/main/src/loaders/ply-loader.js"
    click Preproc "https://github.com/sp5555/websplat/blob/main/src/preprocessing/gaussian-precompute.js"
    click RendererJS "https://github.com/sp5555/websplat/blob/main/src/renderer/renderer.js"
    click Camera "https://github.com/sp5555/websplat/blob/main/src/renderer/camera.js"
    click MeshBuilder "https://github.com/sp5555/websplat/blob/main/src/renderer/mesh-buffer-builder.js"
    click ShaderMgr "https://github.com/sp5555/websplat/blob/main/src/renderer/wgsl-shader/wgsl-shader.js"
    click Transform "https://github.com/sp5555/websplat/blob/main/shaders/transform/transform.wgsl"
    click Sort "https://github.com/sp5555/websplat/blob/main/shaders/sort/sort-bitonic.wgsl"
    click Sort "https://github.com/sp5555/websplat/blob/main/shaders/sort/sort-oe-f.wgsl"
    click Sort "https://github.com/sp5555/websplat/blob/main/shaders/sort/sort-oe.wgsl"
    click Tile "https://github.com/sp5555/websplat/blob/main/shaders/tile/tile.wgsl"
    click RenderStage "https://github.com/sp5555/websplat/blob/main/shaders/render/render.wgsl"
    click RenderStage "https://github.com/sp5555/websplat/blob/main/shaders/render/render-first-splat.wgsl"
    click RenderStage "https://github.com/sp5555/websplat/blob/main/shaders/render/render-flat.wgsl"
    click RenderStage "https://github.com/sp5555/websplat/blob/main/shaders/render/render-outline.wgsl"
    click Utils "https://github.com/sp5555/websplat/blob/main/src/utils/event-emitters.js"
    click Package "https://github.com/sp5555/websplat/blob/main/package.json"

    %% Styles
    classDef cpu fill:#f9f,stroke:#333,stroke-width:1px
    classDef gpu fill:#bbf,stroke:#333,stroke-width:1px
    classDef store fill:#fea,stroke:#333,stroke-width:1px,shape:cylinder
    classDef doc fill:#afa,stroke:#333,stroke-width:1px
    classDef output fill:#afa,stroke:#333,stroke-width:1px,shape:rect
    classDef meta fill:#ddd,stroke:#333,stroke-width:1px,style:dash
```
