# kitware/vtk-js architecture

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

- Interactive diagram: https://gitdiagram.com/kitware/vtk-js
- Repository: https://github.com/kitware/vtk-js

## Overview

##### Project Type and Purpose
- vtk.js is an open-source JavaScript visualization toolkit (a library), not a full-stack app. It provides core data structures, filters, IO, rendering pipelines (WebGL/WebGPU/WebXR), interaction/manipulation APIs, widgets, and remote-rendering proxies to build 3D/volume visualization in the browser.

a. Core Library (Sources/)
- Common – core data structures, math, utilities
- DataModel – PolyData, ImageData, MultiBlock, etc.
- Filters – geometry & image filters (Core, General, Sources, Texture)
- IO – file readers/writers (obj, stl, vtk, image formats) + DataAccessHelpers
- Rendering – pipeline for WebGL/OpenGL/WebGPU/WebXR + SceneGraph + Profiles
- Interaction – manipulators, gesture/keyboard/mouse handlers, UI controls
- Widgets – 3D & 2D interactive widgets & widget manager
- Proxy – remote/ParaView server proxies & data synchronization
b. Examples & Data
- Data/ – sample datasets (VTK geometry, volumes, scenes)
- Examples/ – runnable demos illustrating library use
c. Documentation
- Documentation/ – static site generator, markdown, API docs, tutorials
d. Build & Packaging
- Utilities/webpack, rollup, Babel config, test runner templates
- CI/CD (GitHub workflows)
- dist/ – generated bundles and index.html for the demo site
e. Testing
- Testing/ – unit tests, example-based testing harness

- IO → DataModel: file readers produce PolyData/ImageData
- DataModel → Filters: build and process data pipelines
- Filters → Rendering: mapped to WebGL/WebGPU primitives
- Common & System (timers, Base64, URL fetching) underpin all modules
- Interaction & Widgets → Rendering: attach behaviors to RenderWindow
- Proxy ↔ IO & Rendering: fetch remote geometry, feed into local pipeline
- Examples & Documentation consume the public API exposed by Sources/index.js
- Build & Packaging orchestrate transformation of Sources through Babel/Rollup/Webpack into dist bundles, trigger tests and publishing via CI

##### Architectural Patterns & Principles
- Modular ES6 structure: each feature in its own folder under Sources/
- Pipeline pattern: DataModel → Filters → Rendering
- Proxy pattern for remote rendering (WSLink)
- Factory & State-Builder for widget & representation instantiation
- Adapter/Data-Access abstractions (HTML, HTTP, JSZip) in IO/Core
- Strategy pattern: multiple rendering backends (WebGL vs WebGPU vs WebXR)

##### Essential Elements to Capture
- Public entry point: Sources/index.js → npm module
- Data flow: file import → pipeline → render window
- Extensibility: illustrate where to plug new readers, filters, render passes, widgets
- Build pipeline: Babel → Rollup/Webpack → dist bundles → npm publish
- CI: test suites, example-runner, GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Modules
    subgraph "Core Library" 
        direction TB
        Common["Common"]:::library
        DataModel["DataModel"]:::library
        Filters["Filters"]:::library
        IO["IO"]:::library
        Rendering["Rendering"]:::library
        Interaction["Interaction"]:::library
        Widgets["Widgets"]:::library
        Proxy["Proxy"]:::library
        Entry["Sources/index.js"]:::library
    end

    %% External Entities
    subgraph "Examples & Data & Documentation"
        direction TB
        Examples["Examples"]:::docs
        DataStore["Data"]:::docs
        Documentation["Documentation"]:::docs
    end

    %% Build & Packaging Tools
    subgraph "Build & Packaging" 
        direction TB
        Utilities["Utilities"]:::tools
        RollupConfig["rollup.config.js"]:::tools
        WebpackCommon["webpack.common.js"]:::tools
        WebpackDev["webpack.dev.js"]:::tools
        WebpackProd["webpack.prod.js"]:::tools
        BabelConfig[".babelrc.json"]:::tools
        Dist["dist"]:::tools
    end

    CI["CI/CD\n(.github/workflows/)"]:::infra
    Testing["Testing"]:::infra

    %% Data Flow
    IO -->|"reads files"| DataModel
    DataModel -->|"builds pipelines"| Filters
    Filters -->|"maps to primitives"| Rendering
    Interaction -->|"controls"| Rendering
    Widgets -->|"attach to"| Rendering
    Proxy <-->|"remote fetch"| IO
    Proxy <-->|"sync render state"| Rendering
    Entry -->|"public API"| Examples
    Entry -->|"public API"| Documentation

    %% Build Pipeline
    Entry -->|"transpile"| Utilities
    Utilities -->|"uses configs"| RollupConfig
    Utilities -->|"uses configs"| WebpackCommon
    Utilities -->|"uses configs"| WebpackDev
    Utilities -->|"uses configs"| WebpackProd
    Utilities -->|"uses configs"| BabelConfig
    Utilities -->|"produces"| Dist
    Dist -->|"published via"| CI
    CI -->|"runs"| Testing

    %% Common underpins
    Common -.-> DataModel
    Common -.-> Filters
    Common -.-> IO
    Common -.-> Rendering
    Common -.-> Interaction
    Common -.-> Widgets
    Common -.-> Proxy

    %% Click Events
    click Common "https://github.com/kitware/vtk-js/tree/master/Sources/Common/"
    click DataModel "https://github.com/kitware/vtk-js/tree/master/Sources/Common/DataModel/"
    click Filters "https://github.com/kitware/vtk-js/tree/master/Sources/Filters/"
    click IO "https://github.com/kitware/vtk-js/tree/master/Sources/IO/"
    click Rendering "https://github.com/kitware/vtk-js/tree/master/Sources/Rendering/"
    click Interaction "https://github.com/kitware/vtk-js/tree/master/Sources/Interaction/"
    click Widgets "https://github.com/kitware/vtk-js/tree/master/Sources/Widgets/"
    click Proxy "https://github.com/kitware/vtk-js/tree/master/Sources/Proxy/"
    click Examples "https://github.com/kitware/vtk-js/tree/master/Examples/"
    click DataStore "https://github.com/kitware/vtk-js/tree/master/Data/"
    click Documentation "https://github.com/kitware/vtk-js/tree/master/Documentation/"
    click Utilities "https://github.com/kitware/vtk-js/tree/master/Utilities/"
    click RollupConfig "https://github.com/kitware/vtk-js/blob/master/rollup.config.js"
    click WebpackCommon "https://github.com/kitware/vtk-js/blob/master/webpack.common.js"
    click WebpackDev "https://github.com/kitware/vtk-js/blob/master/webpack.dev.js"
    click WebpackProd "https://github.com/kitware/vtk-js/blob/master/webpack.prod.js"
    click BabelConfig "https://github.com/kitware/vtk-js/blob/master/.babelrc.json"
    click Dist "https://github.com/kitware/vtk-js/tree/master/dist/"
    click CI "https://github.com/kitware/vtk-js/tree/master/.github/workflows/"
    click Testing "https://github.com/kitware/vtk-js/tree/master/Sources/Testing/"

    %% Styles
    classDef library fill:#D6EAF8,stroke:#2980B9,color:#1B4F72;
    classDef tools fill:#EBDEF0,stroke:#9B59B6,color:#512E5F;
    classDef docs fill:#E8F8F5,stroke:#1ABC9C,color:#0E6655;
    classDef infra fill:#FDEDEC,stroke:#E74C3C,color:#641E16;
```
