# iasunsea/chrome-extension-notion-excalidraw-helper architecture

> Architecture diagram of the GitHub repository iasunsea/chrome-extension-notion-excalidraw-helper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iasunsea/chrome-extension-notion-excalidraw-helper
- Repository: https://github.com/iasunsea/chrome-extension-notion-excalidraw-helper

## Overview

##### Project type and purpose
- There is no separate server or cloud component—everything runs in the browser via content scripts, background scripts, and the Notion/Excalidraw web apps.

##### File structure
- Top‐level:
- build/ – bundled extension artifacts (main.bundle.js, assets, manifest.json)
- src/ – TypeScript/JavaScript source (img/, js/, manifest.json)
- utils/ – build helper (utils/build.js)
- webpack.config.js, .babelrc – build tool config
- src/js/ contains three core modules:
- main.js – orchestrator (listens for keyboard shortcuts, coordinates copy/paste)
- notion_api.js – abstraction over Notion’s internal API for uploading/fetching images
- The build step (yarn build) uses webpack to produce a single bundle and to inject the manifest.

##### README for additional insights
- Usage flow:
b. Paste into Notion: extension intercepts paste, uploads image+embedded JSON via notion_api.js.
c. In Notion: when hovering over an image with embedded Excalidraw data, click “Excalidraw” button → data is sent back to Excalidraw for re-import.
- No external backend; communication is between extension scripts and the host page contexts (Excalidraw/Notion).

a. Main components:
- Chrome Extension Contexts:
- Content Script A (runs on Excalidraw domain)
- Content Script B (runs on Notion domain)
- Background Script (optional if messaging is used)
- Host Applications: Excalidraw Web App, Notion Web App
- Build Pipeline: Webpack + Babel
- Storage: chrome.storage (for shortcuts or settings)
b. Relationships & interactions:
1. User triggers keyboard shortcut in Excalidraw → Content Script A captures selection → calls utils.js to serialize data → writes JSON+PNG to clipboard.
2. User pastes into Notion → Content Script B intercepts paste event → notions_api.js uploads blob + JSON payload to Notion server → receives image URL → replaces paste with Notion image block.
3. Hover over image in Notion → Content Script B detects embedded JSON → shows “Excalidraw” button → on click, sends message to Content Script A (via chrome.runtime) with JSON → Excalidraw page re-imports and renders.
4. Build: webpack.config.js bundles src/js into build/main.bundle.js and merges manifests.
c. Architectural patterns & principles:
- Modular content scripts per domain boundary
- Single‐page host apps (Excalidraw/Notion) as external services
- Message passing (chrome.runtime.sendMessage) for cross‐context coordination
- Build‐time bundling to maximize performance and minimize footprint
d. Key technologies:
- Chrome Extension APIs (content scripts, messaging, storage, commands)
- Webpack + Babel for build and transpilation
- Notion’s internal REST/GraphQL endpoints (encapsulated in notion_api.js)
- Excalidraw data model (embedded JSON in PNG data URL)

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Build Pipeline"
    WPACK["webpack.config.js"]:::build
    BABEL[".babelrc"]:::build
    BUILDSCRIPT["utils/build.js"]:::build
    BUNDLE["build/main.bundle.js"]:::build
    MANIFEST_BUNDLE["build/manifest.json"]:::build
    EXCALASSETS["Excalidraw Assets"]:::build
    WPACK & BABEL & BUILDSCRIPT --> BUNDLE
    WPACK & BABEL & BUILDSCRIPT --> MANIFEST_BUNDLE
  end

  subgraph "Extension Internals"
    MANIFEST_SRC["src/manifest.json"]:::extension
    CONTENT["Content Script (Excalidraw/Notion)"]:::extension
    NOTIONAPI["Notion API Abstraction"]:::extension
    UTILS["Shared Utilities"]:::extension
    BG["Background Script / Messaging"]:::extension
    STORAGE["chrome.storage"]:::storage
    MANIFEST_SRC --> CONTENT
    CONTENT --> NOTIONAPI
    CONTENT --> UTILS
    BG --> CONTENT
    STORAGE --> CONTENT
  end

  subgraph "External Hosts"
    EXCAL["Excalidraw Web App"]:::external
    NOTIONWEB["Notion Web App"]:::external
    NOTIONSERVER["Notion Server"]:::cloud
    UserStart["User"]:::user

    UserStart -->|"trigger shortcut"| EXCAL
    EXCAL -->|"serialized selection"| CONTENT
    CONTENT -->|"uses utils.js"| UTILS
    CONTENT -->|"JSON+PNG to clipboard"| EXCAL

    UserStart -->|"paste action"| NOTIONWEB
    NOTIONWEB -->|"intercept paste"| CONTENT
    CONTENT -->|"upload blob+JSON"| NOTIONAPI
    NOTIONAPI -->|"calls REST/GraphQL"| NOTIONSERVER
    NOTIONSERVER -->|"returns image URL"| NOTIONWEB

    NOTIONWEB -->|"hover & click Excalidraw"| CONTENT
    CONTENT -->|"sendMessage"| BG
    BG -->|"forward to Excalidraw script"| CONTENT
    CONTENT -->|"imports JSON"| EXCAL
  end

  click CONTENT "https://github.com/iasunsea/chrome-extension-notion-excalidraw-helper/blob/main/src/js/main.js"
  click NOTIONAPI "https://github.com/iasunsea/chrome-extension-notion-excalidraw-helper/blob/main/src/js/notion_api.js"
  click UTILS "https://github.com/iasunsea/chrome-extension-notion-excalidraw-helper/blob/main/src/js/utils.js"
  click MANIFEST_SRC "https://github.com/iasunsea/chrome-extension-notion-excalidraw-helper/blob/main/src/manifest.json"
  click MANIFEST_BUNDLE "https://github.com/iasunsea/chrome-extension-notion-excalidraw-helper/blob/main/build/manifest.json"
  click BUNDLE "https://github.com/iasunsea/chrome-extension-notion-excalidraw-helper/blob/main/build/main.bundle.js"
  click WPACK "https://github.com/iasunsea/chrome-extension-notion-excalidraw-helper/blob/main/webpack.config.js"
  click BABEL "https://github.com/iasunsea/chrome-extension-notion-excalidraw-helper/blob/main/.babelrc"
  click BUILDSCRIPT "https://github.com/iasunsea/chrome-extension-notion-excalidraw-helper/blob/main/utils/build.js"
  click EXCALASSETS "https://github.com/iasunsea/chrome-extension-notion-excalidraw-helper/tree/main/build/@excalidraw/excalidraw@0.16.1/dist/excalidraw-assets"

  classDef build fill:#ddd,stroke:#999,color:#333
  classDef extension fill:#bbf,stroke:#6699cc,color:#003
  classDef external fill:#bfb,stroke:#4c4,color:#030
  classDef cloud fill:#eef,stroke:#99c,color:#336
  classDef storage fill:#fff5cc,stroke:#cc0,color:#663
  classDef user fill:#fdd,stroke:#d99,color:#900
```
