# bu-cisl/wgpu-idt architecture

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

- Interactive diagram: https://gitdiagram.com/bu-cisl/wgpu-idt
- Repository: https://github.com/bu-cisl/wgpu-idt

## Overview

The product is a browser-based WebGPU framework for intensity diffraction tomography. Its main workflow takes a user-supplied volume and imaging parameters, runs a selected C++ forward model on the GPU, and presents or exports the simulated result. The repository also includes an SSNP reconstruction path and shared GPU compute utilities. The README documents frontend/backend handoffs; source excerpts and the SOURCE INDEX support the backend relationships shown. Unsampled frontend and model internals are represented at subsystem level where their exact call wiring is not visible.

Main entry points: [`src/ssnp/pipeline.cpp`](https://github.com/bu-cisl/wgpu-idt/blob/main/src/ssnp/pipeline.cpp) (SSNP propagation pipeline), [`src/main.cpp`](https://github.com/bu-cisl/wgpu-idt/blob/main/src/main.cpp) (WASM interface), [`src/model_dispatcher.cpp`](https://github.com/bu-cisl/wgpu-idt/blob/main/src/model_dispatcher.cpp) (Model dispatcher), [`web/js/simulation.js`](https://github.com/bu-cisl/wgpu-idt/blob/main/web/js/simulation.js) (Simulation coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser interface"]
  node_file_ui["Volume and controls<br/>[file-handlers.js]"]
  node_decode["Input processing<br/>[file-processing.js]"]
  node_simulation_ui["Simulation coordinator<br/>[simulation.js]"]
  node_visualization["Results display<br/>[visualization.js]"]
end

subgraph group_entry["Runtime entry"]
  node_wasm["WASM interface<br/>[main.cpp]"]
  node_io["Tensor file I/O<br/>[testing_io.cpp]"]
  node_dispatcher["Model dispatcher"]
end

subgraph group_models["Forward models"]
  node_born["Born propagation<br/>[forward.cpp]"]
  node_bpm["BPM propagation<br/>[forward.cpp]"]
  node_ssnp_forward["SSNP forward<br/>[forward.cpp]"]
  node_ssnp_pipeline["SSNP propagation pipeline<br/>[pipeline.cpp]"]
end

subgraph group_reconstruction["SSNP reconstruction"]
  node_reconstruct["SSNP reconstruction<br/>[inverse.h]"]
  node_gradients["Reconstruction gradients<br/>[volume_grad.cpp]"]
end

subgraph group_gpu["GPU compute foundation"]
  node_webgpu_context["WebGPU context and buffers<br/>[webgpu_utils.cpp]"]
  node_fft["FFT transforms<br/>[fft.cpp]"]
  node_dft["DFT transforms<br/>[dft.cpp]"]
  node_pupil["Pupil filtering<br/>[binary_pupil.cpp]"]
  node_intensity["Intensity output<br/>[intensity.cpp]"]
  node_tilt["Illumination tilt<br/>[tilt.cpp]"]
end

node_user(("User"))

node_user -->|"selects inputs"| node_file_ui
node_file_ui -->|"passes volume"| node_decode
node_decode -->|"prepares input"| node_simulation_ui
node_simulation_ui -->|"invokes backend"| node_wasm
node_wasm -->|"dispatches model"| node_dispatcher
node_wasm -->|"reads and writes"| node_io
node_dispatcher -->|"selects model"| node_born
node_dispatcher -->|"selects model"| node_bpm
node_dispatcher -->|"selects model"| node_ssnp_forward
node_wasm -->|"runs reconstruction"| node_reconstruct
node_ssnp_forward -.->|"uses pipeline"| node_ssnp_pipeline
node_ssnp_pipeline -->|"runs transforms"| node_fft
node_ssnp_pipeline -->|"filters field"| node_pupil
node_ssnp_pipeline -->|"initializes field"| node_tilt
node_ssnp_pipeline -->|"creates buffers"| node_webgpu_context
node_fft -->|"uses fallback"| node_dft
node_reconstruct -->|"uses gradients"| node_gradients
node_reconstruct -->|"uses forward pipeline"| node_ssnp_pipeline
node_simulation_ui -->|"displays results"| node_visualization
node_wasm -->|"sends plotted output"| node_visualization
node_visualization -->|"shows measurements"| node_user

click node_file_ui "https://github.com/bu-cisl/wgpu-idt/blob/main/web/js/file-handlers.js"
click node_decode "https://github.com/bu-cisl/wgpu-idt/blob/main/web/js/file-processing.js"
click node_simulation_ui "https://github.com/bu-cisl/wgpu-idt/blob/main/web/js/simulation.js"
click node_visualization "https://github.com/bu-cisl/wgpu-idt/blob/main/web/js/visualization.js"
click node_wasm "https://github.com/bu-cisl/wgpu-idt/blob/main/src/main.cpp"
click node_io "https://github.com/bu-cisl/wgpu-idt/blob/main/src/utils/testing_io.cpp"
click node_dispatcher "https://github.com/bu-cisl/wgpu-idt/blob/main/src/model_dispatcher.cpp"
click node_born "https://github.com/bu-cisl/wgpu-idt/blob/main/src/born/forward.cpp"
click node_bpm "https://github.com/bu-cisl/wgpu-idt/blob/main/src/bpm/forward.cpp"
click node_ssnp_forward "https://github.com/bu-cisl/wgpu-idt/blob/main/src/ssnp/forward.cpp"
click node_ssnp_pipeline "https://github.com/bu-cisl/wgpu-idt/blob/main/src/ssnp/pipeline.cpp"
click node_reconstruct "https://github.com/bu-cisl/wgpu-idt/blob/main/src/ssnp/inverse.h"
click node_gradients "https://github.com/bu-cisl/wgpu-idt/blob/main/src/ssnp/volume_grad/volume_grad.cpp"
click node_webgpu_context "https://github.com/bu-cisl/wgpu-idt/blob/main/src/common/webgpu_utils.cpp"
click node_fft "https://github.com/bu-cisl/wgpu-idt/blob/main/src/common/fft/fft.cpp"
click node_dft "https://github.com/bu-cisl/wgpu-idt/blob/main/src/common/dft/dft.cpp"
click node_pupil "https://github.com/bu-cisl/wgpu-idt/blob/main/src/common/binary_pupil/binary_pupil.cpp"
click node_intensity "https://github.com/bu-cisl/wgpu-idt/blob/main/src/common/intensity/intensity.cpp"
click node_tilt "https://github.com/bu-cisl/wgpu-idt/blob/main/src/common/tilt/tilt.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_file_ui,node_decode,node_simulation_ui,node_visualization,node_user toneBlue
class node_wasm,node_io,node_dispatcher toneAmber
class node_born,node_bpm,node_ssnp_forward,node_ssnp_pipeline toneMint
class node_reconstruct,node_gradients toneRose
class node_webgpu_context,node_fft,node_dft,node_pupil,node_intensity,node_tilt toneIndigo
```

## Components

### Browser interface

- [Volume and controls](https://github.com/bu-cisl/wgpu-idt/blob/main/web/js/file-handlers.js): `web/js/file-handlers.js`
- [Input processing](https://github.com/bu-cisl/wgpu-idt/blob/main/web/js/file-processing.js): `web/js/file-processing.js`
- [Simulation coordinator](https://github.com/bu-cisl/wgpu-idt/blob/main/web/js/simulation.js): `web/js/simulation.js`
- [Results display](https://github.com/bu-cisl/wgpu-idt/blob/main/web/js/visualization.js): `web/js/visualization.js`

### Runtime entry

- [WASM interface](https://github.com/bu-cisl/wgpu-idt/blob/main/src/main.cpp): `src/main.cpp`
- [Tensor file I/O](https://github.com/bu-cisl/wgpu-idt/blob/main/src/utils/testing_io.cpp): `src/utils/testing_io.cpp`
- [Model dispatcher](https://github.com/bu-cisl/wgpu-idt/blob/main/src/model_dispatcher.cpp): `src/model_dispatcher.cpp`

### Forward models

- [Born propagation](https://github.com/bu-cisl/wgpu-idt/blob/main/src/born/forward.cpp): `src/born/forward.cpp`
- [BPM propagation](https://github.com/bu-cisl/wgpu-idt/blob/main/src/bpm/forward.cpp): `src/bpm/forward.cpp`
- [SSNP forward](https://github.com/bu-cisl/wgpu-idt/blob/main/src/ssnp/forward.cpp): `src/ssnp/forward.cpp`
- [SSNP propagation pipeline](https://github.com/bu-cisl/wgpu-idt/blob/main/src/ssnp/pipeline.cpp): `src/ssnp/pipeline.cpp`

### SSNP reconstruction

- [SSNP reconstruction](https://github.com/bu-cisl/wgpu-idt/blob/main/src/ssnp/inverse.h): `src/ssnp/inverse.h`
- [Reconstruction gradients](https://github.com/bu-cisl/wgpu-idt/blob/main/src/ssnp/volume_grad/volume_grad.cpp): `src/ssnp/volume_grad/volume_grad.cpp`

### GPU compute foundation

- [WebGPU context and buffers](https://github.com/bu-cisl/wgpu-idt/blob/main/src/common/webgpu_utils.cpp): `src/common/webgpu_utils.cpp`
- [FFT transforms](https://github.com/bu-cisl/wgpu-idt/blob/main/src/common/fft/fft.cpp): `src/common/fft/fft.cpp`
- [DFT transforms](https://github.com/bu-cisl/wgpu-idt/blob/main/src/common/dft/dft.cpp): `src/common/dft/dft.cpp`
- [Pupil filtering](https://github.com/bu-cisl/wgpu-idt/blob/main/src/common/binary_pupil/binary_pupil.cpp): `src/common/binary_pupil/binary_pupil.cpp`
- [Intensity output](https://github.com/bu-cisl/wgpu-idt/blob/main/src/common/intensity/intensity.cpp): `src/common/intensity/intensity.cpp`
- [Illumination tilt](https://github.com/bu-cisl/wgpu-idt/blob/main/src/common/tilt/tilt.cpp): `src/common/tilt/tilt.cpp`

### Other components

- **User**

## Connections

- User → Volume and controls: selects inputs (evidence: `README.md`)
- Volume and controls → Input processing: passes volume (evidence: `README.md`)
- Input processing → Simulation coordinator: prepares input (evidence: `README.md`)
- Simulation coordinator → WASM interface: invokes backend (evidence: `README.md`)
- WASM interface → Model dispatcher: dispatches model (evidence: `src/main.cpp`)
- WASM interface → Tensor file I/O: reads and writes (evidence: `src/main.cpp`)
- Model dispatcher → Born propagation: selects model
- Model dispatcher → BPM propagation: selects model
- Model dispatcher → SSNP forward: selects model
- WASM interface → SSNP reconstruction: runs reconstruction (evidence: `src/main.cpp`)
- SSNP forward → SSNP propagation pipeline: uses pipeline
- SSNP propagation pipeline → FFT transforms: runs transforms (evidence: `src/ssnp/pipeline.cpp`)
- SSNP propagation pipeline → Pupil filtering: filters field (evidence: `src/ssnp/pipeline.cpp`)
- SSNP propagation pipeline → Illumination tilt: initializes field (evidence: `src/ssnp/pipeline.cpp`)
- SSNP propagation pipeline → WebGPU context and buffers: creates buffers (evidence: `src/ssnp/pipeline.cpp`)
- FFT transforms → DFT transforms: uses fallback (evidence: `src/common/fft/fft.cpp`)
- SSNP reconstruction → Reconstruction gradients: uses gradients (evidence: `src/ssnp/inverse.h`)
- SSNP reconstruction → SSNP propagation pipeline: uses forward pipeline (evidence: `src/ssnp/inverse.h`)
- Simulation coordinator → Results display: displays results (evidence: `README.md`)
- WASM interface → Results display: sends plotted output (evidence: `src/main.cpp`)
- Results display → User: shows measurements (evidence: `README.md`)
