# iddan/react-native-canvas architecture

> Architecture diagram of the GitHub repository iddan/react-native-canvas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iddan/react-native-canvas
- Repository: https://github.com/iddan/react-native-canvas

## Overview

##### Project type and purpose
- This is an open‑source React Native library (“react‑native‑canvas”) that provides a Canvas component by embedding an HTML Canvas inside a React Native WebView and bridging the standard Canvas API across the native–JS boundary.

##### Main components
A. React Native Layer
– **Example App / Consumer**: Your React Native application that imports `<Canvas />` from react‑native‑canvas.
– **Canvas React Component** (`src/Canvas.js`): Exposes a `<Canvas />` component and handles props, refs, and lifecycle hooks.
B. Bridge / Messaging Layer
– **react-native-webview Native Module**: The native iOS/Android WebView view and its postMessage–onMessage plumbing.
– **Message Bus** (`src/Bus.js`): A JS event bus in the RN context that serializes Canvas API calls into messages.
– **WebView Binders** (`src/webview-binders.js`): Deserializes inbound messages from RN, routes them to the correct proxy object in the WebView context, and serializes return values back.
C. WebView (HTML/JS) Layer
– **index.html** / **index.html.js**: The HTML shell loaded into the WebView, which in turn loads `webview.js`.
– **webview.js**: Bootstraps the Canvas API proxies in the WebView’s global scope and wires up `window.onMessage` to your Binders.
– **Canvas API Proxies** (`src/CanvasRenderingContext2D.js`, `src/CanvasGradient.js`, `src/Image.js`, `src/Path2D.js`, `src/ImageData.js`): Implement Canvas and related APIs, proxying method calls to the actual DOM `<canvas>` element.
– **HTML Canvas Element**: The real `<canvas>` in the WebView’s DOM that executes drawing commands.
D. Support Modules
– **autoscale-canvas.ts**: A helper to scale the canvas for device pixel ratios.
– **bundle-html.js**: Bundles the HTML/JS resources for deployment.

##### Relationships and data flow
- Developer calls `canvas.getContext("2d")` in React Native →
→ Canvas Component invokes `Bus.send(“getContext”, …)` →
→ postMessage (via react‑native‑webview) to WebView →
→ WebView Binders receive message, look up the proxy object, call underlying CanvasRenderingContext2D method on real `<canvas>` →
→ If the method returns a value (e.g. `toDataURL()`), Binders serialize it and postMessage it back →
→ Bus receives it, resolves the Promise in RN, developer code continues.

##### Architectural patterns and design principles
– **Facade/Adapter Pattern**: `Canvas.js` and `CanvasRenderingContext2D.js` expose the standard HTML Canvas API to RN code, hiding the underlying WebView complexity.
– **Message Bus / Proxy RPC**: `Bus.js` centralizes message serialization; each Canvas API call is a remote procedure call over postMessage.
– **Separation of Concerns**: RN component (UI & props) is decoupled from WebView environment (actual rendering).

##### Detailed capture
– Illustrate the **Bus.js** API registry (mapping method names to message IDs).
– Optionally annotate the **autoscale-canvas** utility’s role in initializing the real `<canvas>` dimensions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% React Native Layer
    subgraph "React Native Layer"
        ExampleApp["Example App / Consumer"]:::rn
        CanvasComp["Canvas Component\n(src/Canvas.js)"]:::rn
    end

    %% Bridge / Messaging Layer
    subgraph "Bridge / Messaging Layer"
        Bus["Message Bus\n(src/Bus.js)"]:::bus
        RNWebView["react-native-webview Native Module"]:::bus
    end

    %% WebView / HTML Layer
    subgraph "WebView / HTML Layer"
        HTMLShell["index.html / index.html.js"]:::web
        WebviewJS["webview.js\n(src/webview.js)"]:::web
        Binders["WebView Binders\n(src/webview-binders.js)"]:::web
        subgraph "Canvas API Proxies"
            Context2D["CanvasRenderingContext2D.js"]:::web
            Gradient["CanvasGradient.js"]:::web
            Img["Image.js"]:::web
            Path2D["Path2D.js"]:::web
            ImageData["ImageData.js"]:::web
        end
        DOMCanvas["HTML Canvas Element"]:::web
    end

    %% Support Modules
    subgraph "Support Modules"
        Autoscale["autoscale-canvas.ts"]:::supp
        BundleHTML["bundle-html.js"]:::supp
    end

    %% Data Flow
    ExampleApp -->|"imports <Canvas/>"| CanvasComp
    CanvasComp -->|"Bus.send(getContext)"| Bus
    Bus -->|"postMessage(getContext)"| RNWebView
    RNWebView -->|"window.onMessage"| WebviewJS
    WebviewJS -->|"bind message"| Binders
    Binders -->|"invoke getContext"| Context2D
    Context2D -->|"calls real API"| DOMCanvas
    DOMCanvas -->|"returns value"| Context2D
    Context2D -->|"serialize response"| Binders
    Binders -->|"postMessage(response)"| RNWebView
    RNWebView -->|"window.onMessage"| Bus
    Bus -->|"resolve Promise"| CanvasComp

    %% Additional flows
    WebviewJS -->|"uses autoscale"| Autoscale
    BundleHTML --- HTMLShell

    %% Click Events
    click ExampleApp "https://github.com/iddan/react-native-canvas/blob/master/example/app/index.tsx"
    click CanvasComp "https://github.com/iddan/react-native-canvas/blob/master/src/Canvas.js"
    click Bus "https://github.com/iddan/react-native-canvas/blob/master/src/Bus.js"
    click WebviewJS "https://github.com/iddan/react-native-canvas/blob/master/src/webview.js"
    click Binders "https://github.com/iddan/react-native-canvas/blob/master/src/webview-binders.js"
    click HTMLShell "https://github.com/iddan/react-native-canvas/blob/master/src/index.html"
    click Context2D "https://github.com/iddan/react-native-canvas/blob/master/src/CanvasRenderingContext2D.js"
    click Gradient "https://github.com/iddan/react-native-canvas/blob/master/src/CanvasGradient.js"
    click Img "https://github.com/iddan/react-native-canvas/blob/master/src/Image.js"
    click Path2D "https://github.com/iddan/react-native-canvas/blob/master/src/Path2D.js"
    click ImageData "https://github.com/iddan/react-native-canvas/blob/master/src/ImageData.js"
    click Autoscale "https://github.com/iddan/react-native-canvas/blob/master/src/autoscale-canvas.ts"
    click BundleHTML "https://github.com/iddan/react-native-canvas/blob/master/bundle-html.js"

    %% Styles
    classDef rn fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef bus fill:#DFFFD0,stroke:#228B22,color:#228B22;
    classDef web fill:#FFE7C0,stroke:#FF8C00,color:#FF8C00;
    classDef supp fill:#F0E6FF,stroke:#9400D3,color:#9400D3;
```
