# episphere/imagebox3 architecture

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

- Interactive diagram: https://gitdiagram.com/episphere/imagebox3
- Repository: https://github.com/episphere/imagebox3

## Overview

##### Project Type and Purpose
- Type: A zero-footprint, client-only JavaScript library (not a full-stack app).
- Purpose: Enable browsers to extract image patches directly from large remote TIFF/WSI files via HTTP Range Requests, with no server-side tiling.

##### Main Architectural Components
a. Host Application (consuming page or framework)
b. ImageBox3 Core Module (imagebox3.mjs / imagebox3.js)
c. Decoder Layer
– decoders.json (configuration)
– decoder_33005.js (example JPEG2000 codec)
– Additional decoder plugins
d. HTTP Range Request Engine (built into Core)
e. Remote Storage / WSI File Server (S3, HTTP server)
f. Browser Runtime
– Fetch API (HTTP Range)
– Blob & URL APIs
– Optional Service Worker (demo/serviceWorker)
g. Demo UI (index.html, index.js, CSS) – illustrates usage
h. Documentation Site (docs/) – static JSDoc pages

##### Relationships & Data Flows
1. Host App loads ImageBox3 module
→ initializes instance with URL or File object
2. Core Module issues HTTP Range Requests (Fetch API)
→ requests specific byte ranges from Remote Storage
3. Fetched ArrayBuffer slices flow into Decoder Layer
→ selects appropriate codec (via decoders.json)
→ decodes compressed tiles to raw image data
4. Core Module assembles raw pixels, re-encodes as PNG Blob
→ returns Blob promise to Host App
5. Host App renders Blob via Object URL in an <img> tag
6. (In Demo) Service Worker can intercept range requests and cache byte ranges

##### Architectural Patterns & Design Principles
- Modular “plugin” decoders (Strategy Pattern)
- Single-responsibility separation:
– Core orchestration (init, metadata parsing, request routing)
– Decoding abstraction (decoders/)
– Presentation/demo separated (demo/, docs/)
- Lazy loading of decoders only when needed
- Zero-footprint: no server-side; all computation in browser

##### Technologies & Libraries
- ECMAScript Modules (imagebox3.mjs)
- HTTP Range Requests (Fetch API with Range header)
- TIFF/WSI metadata parsing (in Core)
- Codec implementations in pure JS (decoder_33005.js)
- Service Worker API (demo)
- JSDoc-generated static docs

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Host Application"
        HA_HTML["index.html"]:::demo
        HA_JS["index.js"]:::demo
    end

    subgraph "ImageBox3 Core Module"
        Core["ImageBox3 Core"]:::core
    end

    subgraph "Browser Runtime"
        FetchAPI["Fetch API (HTTP Range)"]:::api
        BlobURL["Blob & URL API"]:::api
        SWRuntime["Service Worker API"]:::api
    end

    subgraph "Remote Storage / WSI File Server"
        RemoteStorage["S3 / HTTP Server"]:::external
    end

    subgraph "Decoder Layer (Plugin Strategy)"
        DecodersJSON["decoders.json"]:::core
        DecoderPlugin["decoder_33005.js"]:::core
        MorePlugins["decoders/"]:::core
    end

    subgraph "Demo UI"
        DemoHTML["demo/serviceWorker/index.html"]:::demo
        DemoJS["demo/serviceWorker/index.js"]:::demo
        DemoCSS["demo/serviceWorker/imgBox.css"]:::demo
    end

    subgraph "Service Worker (Demo)"
        SW["serviceWorker"]:::api
    end

    subgraph "Documentation Site"
        Docs["docs/"]:::docs
    end

    subgraph "Project Metadata"
        README["README.md"]:::docs
        LICENSE["LICENSE"]:::docs
        GITIGNORE[".gitignore"]:::docs
    end

    HA_HTML -->|"loads module"| Core
    HA_JS -->|"loads module"| Core

    Core -->|"init &metadata parsing"| FetchAPI
    FetchAPI -->|"Range Request"| RemoteStorage
    RemoteStorage -->|"ArrayBuffer response"| FetchAPI
    FetchAPI -->|"sliced ArrayBuffer"| Core

    Core -->|"select codec via decoders.json"| DecodersJSON
    Core --> DecodersJSON --> DecoderPlugin
    Core --> MorePlugins
    DecoderPlugin -->|"decoded pixel data"| Core

    Core -->|"assemble PNG Blob"| BlobURL
    BlobURL -->|"Object URL"| HA_HTML

    DemoHTML -->|"register serviceWorker"| SW
    DemoJS -->|"register serviceWorker"| SW
    SWRuntime -->|"intercepts RangeRequest"| FetchAPI
    SW -->|"caches byte ranges"| SWRuntime

    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef external fill:#d4edda,stroke:#333,stroke-width:1px
    classDef api fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef demo fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef docs fill:#f8f9fa,stroke:#333,stroke-width:1px

    click HA_HTML "https://github.com/episphere/imagebox3/blob/main/index.html"
    click HA_JS "https://github.com/episphere/imagebox3/blob/main/index.js"
    click Core "https://github.com/episphere/imagebox3/blob/main/imagebox3.mjs"
    click Core "https://github.com/episphere/imagebox3/blob/main/imagebox3.js"
    click DecodersJSON "https://github.com/episphere/imagebox3/blob/main/decoders/decoders.json"
    click DecoderPlugin "https://github.com/episphere/imagebox3/blob/main/decoders/decoder_33005.js"
    click MorePlugins "https://github.com/episphere/imagebox3/tree/main/decoders/"
    click DemoHTML "https://github.com/episphere/imagebox3/blob/main/demo/serviceWorker/index.html"
    click DemoJS "https://github.com/episphere/imagebox3/blob/main/demo/serviceWorker/index.js"
    click DemoCSS "https://github.com/episphere/imagebox3/blob/main/demo/serviceWorker/imgBox.css"
    click SW "https://github.com/episphere/imagebox3/tree/main/demo/serviceWorker/serviceWorker"
    click Docs "https://github.com/episphere/imagebox3/tree/main/docs/"
    click README "https://github.com/episphere/imagebox3/blob/main/README.md"
    click LICENSE "https://github.com/episphere/imagebox3/tree/main/LICENSE"
    click GITIGNORE "https://github.com/episphere/imagebox3/blob/main/.gitignore"
```
