# poloclub/diffusion-explainer architecture

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

- Interactive diagram: https://gitdiagram.com/poloclub/diffusion-explainer
- Repository: https://github.com/poloclub/diffusion-explainer

## Overview

##### Project type and purpose
- This is a static, client-side interactive visualization tool (an open-source “Diffusion Explainer” web app).
- Purpose: let users experiment with Stable Diffusion text-to-image transformations in the browser, visualizing intermediate stages (latent vectors, denoising steps, UMAP projections).

##### File structure
- Top-level:
- index.html + style.css – single-page HTML/CSS UI
- js/ – JavaScript modules (controllers, visualization logic, UI components, data loaders)
- assets/ – static data (images, latent-viz frames, JSON vectors, UMAP coords, noises)
- python/compress.py – build-time script for compressing or generating assets
- No “backend” directory or server code: the app is purely static, served over HTTP.
- The js/ folder shows an MVC-like pattern:
- controller.js orchestrates user interactions
- denoise_*.js, text_*.js handle algorithmic data processing
- prompts.js, description.js, header.js populate UI text and prompts
- assets/umap and assets/json hold precomputed data loaded at runtime; assets/img and assets/latent_viz supply visual frames.

##### Insights from the README
- Confirms it’s a browser-only tool, no installation, runs via `python -m http.server`.
- Data is static, loaded via AJAX/fetch.
- Libraries and dependencies: plain JS, no framework dependencies listed (likely vanilla JS or small libs inlined).

a. Main components:
- Static HTTP Server (serves files)
- Browser (client)
– UI Layer (index.html, style.css, DOM)
– JS Controller Layer (js/controller.js + header.js + prompts.js + description.js)
– Data Processing Modules (js/denoise_l2expl.js, js/text_l3expl.js, etc.)
– Visualization Layer (renders images, latent projections, UMAP via Canvas or SVG)
– Asset Loader (fetches JSON, images, UMAP coords)
- Build-Time Pipeline (python/compress.py → generates compressed assets, latent viz frames, JSON)
b. Relationships & interactions:
- Browser ←fetch— HTTP Server serves index.html, JS, CSS, assets
- User actions in UI → Controller → invokes Data Processing → Visualization Layer
- Asset Loader fetches JSON & images on demand → passed to processing modules → displayed
- Build-Time Pipeline is separate: transforms raw data into assets/, not involved at runtime
c. Architectural patterns & design principles:
- Single-Page Application (SPA) pattern – no full page reloads, all logic in JS
- MVC-like separation: UI/view vs controller vs data processing modules
- Precompute-at-build: heavy computation (UMAP, denoise outputs) done ahead of time for fast client interaction
- Modular JS: each feature in its own file, easy to extend (e.g., add new denoising explainer)
d. Key technologies/frameworks:
- Plain HTML/CSS/JavaScript, no heavy frameworks
- JSON assets for data interchange
- Python script (compress.py) for asset generation
- Possibly D3.js or Canvas APIs (if used inside js/visualization modules)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Global components
    StaticHTTP["HTTP Server\n(serves static files)"]:::infra
    BuildPipeline["Build Pipeline\npython/compress.py"]:::build
    Browser["Browser"]:::runtime

    %% Build Pipeline to Assets
    BuildPipeline --> |"generates assets"| Assets

    %% Runtime flow
    StaticHTTP --> |"serves files"| Browser
    Browser --> UI_HTML
    Browser --> UI_CSS

    %% Browser subcomponents
    subgraph "Browser"
        direction TB
        subgraph "UI Layer"
            direction TB
            UI_HTML["index.html"]:::runtime
            UI_CSS["style.css"]:::runtime
        end

        subgraph "Controller Layer"
            direction TB
            ControllerMain["controller.js"]:::runtime
            HeaderJS["header.js"]:::runtime
            PromptsJS["prompts.js"]:::runtime
            DescriptionJS["description.js"]:::runtime
        end

        subgraph "Data Processing Modules"
            direction TB
            DenoiseL2["denoise_l2expl.js"]:::runtime
            DenoiseL3["denoise_l3expl.js"]:::runtime
            TextL2["text_l2expl.js"]:::runtime
            TextL3["text_l3expl.js"]:::runtime
        end

        subgraph "Visualization Layer"
            direction TB
            CompareJS["compare.js"]:::runtime
            ArchitectureJS["architecture.js"]:::runtime
            FunctionJS["function.js"]:::runtime
        end

        subgraph "Asset Loader"
            direction TB
            FunctionFetch["function.js"]:::runtime
        end

        %% Internal flows
        UI_HTML --> ControllerMain
        UI_CSS --> ControllerMain
        ControllerMain --> HeaderJS
        ControllerMain --> PromptsJS
        ControllerMain --> DescriptionJS
        ControllerMain --> DenoiseL2
        ControllerMain --> TextL2
        ControllerMain --> DenoiseL3
        ControllerMain --> TextL3
        DenoiseL2 --> CompareJS
        DenoiseL3 --> CompareJS
        TextL2 --> ArchitectureJS
        TextL3 --> ArchitectureJS
        CompareJS --> FunctionJS
        ArchitectureJS --> FunctionJS
        FunctionJS --> FunctionFetch
        FunctionFetch -->|fetch assets| StaticHTTP
    end

    %% Static Assets
    subgraph "Assets" 
        direction TB
        ImgFrames["assets/img/"]:::assets
        TextVector["assets/json/text_vector.json"]:::assets
        LatentViz["assets/latent_viz/"]:::assets
        UMAPData["assets/umap/umap_0.99_15_0.json"]:::assets
        Noises["assets/noises/"]:::assets
        Preview["assets/preview/"]:::assets
    end

    %% Asset flow
    StaticHTTP --> ImgFrames
    StaticHTTP --> TextVector
    StaticHTTP --> LatentViz
    StaticHTTP --> UMAPData
    StaticHTTP --> Noises
    StaticHTTP --> Preview

    %% Click Events
    click StaticHTTP "https://github.com/poloclub/diffusion-explainer/tree/main//"
    click UI_HTML "https://github.com/poloclub/diffusion-explainer/blob/main/index.html"
    click UI_CSS "https://github.com/poloclub/diffusion-explainer/blob/main/style.css"
    click ControllerMain "https://github.com/poloclub/diffusion-explainer/blob/main/js/controller.js"
    click HeaderJS "https://github.com/poloclub/diffusion-explainer/blob/main/js/header.js"
    click PromptsJS "https://github.com/poloclub/diffusion-explainer/blob/main/js/prompts.js"
    click DescriptionJS "https://github.com/poloclub/diffusion-explainer/blob/main/js/description.js"
    click DenoiseL2 "https://github.com/poloclub/diffusion-explainer/blob/main/js/denoise_l2expl.js"
    click DenoiseL3 "https://github.com/poloclub/diffusion-explainer/blob/main/js/denoise_l3expl.js"
    click TextL2 "https://github.com/poloclub/diffusion-explainer/blob/main/js/text_l2expl.js"
    click TextL3 "https://github.com/poloclub/diffusion-explainer/blob/main/js/text_l3expl.js"
    click CompareJS "https://github.com/poloclub/diffusion-explainer/blob/main/js/compare.js"
    click ArchitectureJS "https://github.com/poloclub/diffusion-explainer/blob/main/js/architecture.js"
    click FunctionJS "https://github.com/poloclub/diffusion-explainer/blob/main/js/function.js"
    click FunctionFetch "https://github.com/poloclub/diffusion-explainer/blob/main/js/function.js"
    click ImgFrames "https://github.com/poloclub/diffusion-explainer/tree/main/assets/img/"
    click TextVector "https://github.com/poloclub/diffusion-explainer/blob/main/assets/json/text_vector.json"
    click LatentViz "https://github.com/poloclub/diffusion-explainer/tree/main/assets/latent_viz/"
    click UMAPData "https://github.com/poloclub/diffusion-explainer/blob/main/assets/umap/umap_0.99_15_0.json"
    click Noises "https://github.com/poloclub/diffusion-explainer/tree/main/assets/noises/"
    click Preview "https://github.com/poloclub/diffusion-explainer/tree/main/assets/preview/"
    click BuildPipeline "https://github.com/poloclub/diffusion-explainer/blob/main/python/compress.py"

    %% Styles
    classDef runtime fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef assets fill:#90EE90,stroke:#000,stroke-width:1px
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef infra fill:#F0E68C,stroke:#000,stroke-width:1px
```
