# r3ner3n/nodeclipper-for-notebooklm architecture

> Architecture diagram of the GitHub repository r3ner3n/nodeclipper-for-notebooklm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/r3ner3n/nodeclipper-for-notebooklm
- Repository: https://github.com/r3ner3n/nodeclipper-for-notebooklm

## Overview

1. **Overall architecture**
   - This is a **Chrome Extension (Manifest V3)**, not a standalone web app.
   - It is fully client-side: there is **no backend server** or external API in the core architecture.
   - The extension is built from TypeScript with **Vite** and packaged into a `dist/` folder for loading into Chrome.

2. **Primary runtime pieces**
   - **Side Panel UI**: the user-facing control surface where crawling starts, selection happens, and export is triggered.
   - **Background Service Worker**: the orchestration layer that performs crawling, manages the discovered site tree, and handles export/download actions.
   - **Offscreen Document**: a hidden DOM-capable context used for HTML parsing and conversion, because the service worker cannot do DOM-based extraction directly.

3. **UI boundary: `src/side_panel`**
   - `panel.ts` and `panel.css` implement the interactive panel shown on the right side of Chrome.
   - This UI owns the main user workflow: set crawl depth, start crawling, inspect the tree, select nodes, preview URLs, and export.
   - The panel also includes a **language toggle (JA/EN)**, with preference stored locally in `localStorage`.

4. **Orchestration boundary: `src/background`**
   - `background/index.ts` acts as the central coordinator.
   - It runs the **crawl queue**, applies the **breadth-first crawl strategy**, enforces the **500 ms request delay**, and restricts traversal to the **same domain**.
   - It also aggregates crawl results into the tree structure consumed by the side panel and prepares the export output.

5. **Parsing boundary: `src/offscreen`**
   - `offscreen/offscreen.ts` is the document-processing layer.
   - It uses **Mozilla Readability** to isolate article/main content from full HTML.
   - It uses **Turndown** to convert cleaned HTML into Markdown, including link-style handling for media when appropriate.
   - This separation is important because parsing depends on DOM APIs that are unavailable in the service worker.

6. **Data flow: crawl to tree**
   - The user starts from the current page in Chrome.
   - The side panel sends a crawl request to the background worker.
   - The background worker fetches pages, discovers links, and builds a **collapsible tree of pages**.
   - That tree is streamed back to the side panel for display and selection.

7. **Data flow: selection to export**
   - The user selects individual pages or subtrees in the panel.
   - Parent selection propagates to descendants, and partially selected branches show an **indeterminate** state.
   - On export, the background worker merges the selected pages into a **single Markdown file** and writes outputs into a timestamped folder in **Downloads**.

8. **Media handling**
   - The tree can include non-HTML nodes such as PDFs, images, audio, and video.
   - These can be downloaded individually from the panel.
   - The export flow keeps media separate from the merged Markdown so the final NotebookLM import can include both the `.md` source and any relevant files.

9. **Extension surfaces and packaging**
   - `public/manifest.json` defines the MV3 extension surfaces and permissions.
   - `public/side_panel/index.html` and `public/offscreen/index.html` are the HTML entrypoints for the two non-background contexts.
   - `public/icons/` contains the extension assets shown in Chrome.

10. **Key architectural constraints**
   - The system is designed around **browser session access**, which is why it can crawl login-protected pages that external scrapers typically cannot.
   - The use of a **side panel + service worker + offscreen document** is the core architectural pattern.
   - All important state is local to the extension/runtime; there is no remote persistence layer.

11. **Repository-level structure**
   - `src/types` holds shared type definitions used across the three runtime contexts.
   - `vite.config.ts`, `tsconfig.json`, and `package.json` define the build pipeline and TypeScript packaging.
   - `.devcontainer/` is developer tooling only; it does not affect runtime architecture.

12. **What to show in an architecture diagram**
   - Draw Chrome as the host boundary.
   - Inside it, show three boxes: **Side Panel UI**, **Background Service Worker**, and **Offscreen Document**.
   - Show the data path: **current page → crawl queue/tree in background → tree state in side panel → selection/export → downloads folder**.
   - Show the parsing path: **fetched HTML → offscreen Readability/Turndown → Markdown**.

Main entry points: [`src/background/index.ts`](https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/src/background/index.ts) (Background SW), [`src/side_panel/panel.ts`](https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/src/side_panel/panel.ts) (Side Panel), [`src/offscreen/offscreen.ts`](https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/src/offscreen/offscreen.ts) (Offscreen Doc), [`public/manifest.json`](https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/public/manifest.json) (Manifest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chrome["Chrome host"]
  node_chrome["Chrome<br/>host"]
  node_side_panel["Side Panel<br/>ui<br/>[panel.ts]"]
  node_background["Background SW<br/>orchestrator<br/>[index.ts]"]
  node_offscreen["Offscreen Doc<br/>parser<br/>[offscreen.ts]"]
  node_current_page["Current Page<br/>tab source"]
  node_crawl_queue["Crawl Queue"]
  node_site_tree[("Site Tree<br/>tree state")]
  node_selection["Selection<br/>ui state"]
  node_export_job["Export Job<br/>merge job"]
  node_markdown_output["Markdown File<br/>export artifact"]
  node_downloads[("Downloads<br/>browser output")]
  node_media_files["Media Files<br/>assets"]
  node_readability["Readability<br/>content extractor"]
  node_turndown["Turndown<br/>html-to-md"]
end

subgraph group_build["Build & packaging"]
  node_manifest["Manifest<br/>mv3 config<br/>[manifest.json]"]
  node_build_tooling["Vite Build<br/>tooling<br/>[vite.config.ts]"]
end

node_shared_types["Shared Types<br/>type defs<br/>[index.ts]"]

node_chrome -->|"hosts"| node_side_panel
node_chrome -->|"hosts"| node_background
node_chrome -->|"hosts"| node_offscreen
node_side_panel -->|"crawl request"| node_background
node_current_page -->|"seed URL"| node_background
node_background -->|"enqueue"| node_crawl_queue
node_crawl_queue -->|"dequeue"| node_background
node_background -->|"build tree"| node_site_tree
node_site_tree -->|"stream state"| node_side_panel
node_side_panel -->|"select nodes"| node_selection
node_selection -->|"export request"| node_background
node_background -->|"parse HTML"| node_offscreen
node_offscreen -->|"extract content"| node_readability
node_readability -->|"clean HTML"| node_turndown
node_turndown -->|"render markdown"| node_markdown_output
node_background -->|"merge files"| node_markdown_output
node_markdown_output -->|"write export"| node_downloads
node_background -->|"download media"| node_media_files
node_media_files -->|"store files"| node_downloads
node_side_panel -->|"single download"| node_media_files
node_manifest -->|"declares"| node_side_panel
node_manifest -->|"declares"| node_background
node_manifest -->|"declares"| node_offscreen
node_shared_types -->|"shared contract"| node_side_panel
node_shared_types -->|"shared contract"| node_background
node_shared_types -->|"shared contract"| node_offscreen
node_build_tooling -->|"packages"| node_manifest

click node_side_panel "https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/src/side_panel/panel.ts"
click node_background "https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/src/background/index.ts"
click node_offscreen "https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/src/offscreen/offscreen.ts"
click node_shared_types "https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/src/types/index.ts"
click node_manifest "https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/public/manifest.json"
click node_build_tooling "https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/vite.config.ts"

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_chrome,node_side_panel,node_background,node_offscreen,node_current_page,node_crawl_queue,node_site_tree,node_selection,node_export_job,node_markdown_output,node_downloads,node_media_files,node_readability,node_turndown toneBlue
class node_manifest,node_build_tooling toneAmber
class node_shared_types toneNeutral
```

## Components

### Chrome host

Extension runtime surfaces inside Chrome

- **Chrome**: host · Browser host boundary for the extension
- [Side Panel](https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/src/side_panel/panel.ts): ui · User control surface for crawling, selection, preview, and export · `src/side_panel/panel.ts`
- [Background SW](https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/src/background/index.ts): orchestrator · Central coordinator for crawl, tree building, and export · `src/background/index.ts`
- [Offscreen Doc](https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/src/offscreen/offscreen.ts): parser · DOM-capable parsing and Markdown conversion context · `src/offscreen/offscreen.ts`
- **Current Page**: tab source · Starting point for session-aware crawling
- **Crawl Queue**: queue · Breadth-first crawl worklist with delay and same-domain rules
- **Site Tree**: tree state · Collapsible discovered page tree shared with the panel
- **Selection**: ui state · Chosen pages and subtrees with indeterminate propagation
- **Export Job**: merge job · Builds the final Markdown bundle from selected pages
- **Markdown File**: export artifact · Merged Markdown produced for NotebookLM import
- **Downloads**: browser output · Chrome download destination for export and media files
- **Media Files**: assets · Non-HTML downloads such as PDFs, images, audio, and video
- **Readability**: content extractor · Isolates main article content from fetched HTML
- **Turndown**: html-to-md · Converts cleaned HTML into Markdown with link handling

### Build & packaging

Vite/TypeScript build and extension assets

- [Manifest](https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/public/manifest.json): mv3 config · Defines extension surfaces, permissions, and entrypoints · `public/manifest.json`
- [Vite Build](https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/vite.config.ts): tooling · TypeScript/Vite packaging into the dist folder · `vite.config.ts`

### Other components

- [Shared Types](https://github.com/r3ner3n/nodeclipper-for-notebooklm/blob/main/src/types/index.ts): type defs · Common interfaces used across all runtime contexts · `src/types/index.ts`

## Connections

- Chrome → Side Panel: hosts · Chrome hosts the side panel surface
- Chrome → Background SW: hosts · Chrome runs the service worker
- Chrome → Offscreen Doc: hosts · Chrome provides the hidden document context
- Side Panel → Background SW: crawl request · User starts crawling from the panel
- Current Page → Background SW: seed URL · Crawl begins from the active tab/session page
- Background SW → Crawl Queue: enqueue · Background worker schedules breadth-first crawl work
- Crawl Queue → Background SW: dequeue · Queued pages are fetched with domain and delay rules
- Background SW → Site Tree: build tree · Discovered pages are aggregated into the site tree
- Site Tree → Side Panel: stream state · Tree state is rendered for inspection and selection
- Side Panel → Selection: select nodes · Parent and descendant selection is managed in the UI
- Selection → Background SW: export request · Selected pages are handed to the export pipeline
- Background SW → Offscreen Doc: parse HTML · Fetched page HTML is sent to the offscreen document
- Offscreen Doc → Readability: extract content · Readability isolates the main article or content region
- Readability → Turndown: clean HTML · Cleaned content is prepared for Markdown conversion
- Turndown → Markdown File: render markdown · Converted Markdown is assembled for export
- Background SW → Markdown File: merge files · Background worker merges selected pages into one Markdown file
- Markdown File → Downloads: write export · Timestamped export folder is written to Downloads
- Background SW → Media Files: download media · Media assets are saved separately from the Markdown bundle
- Media Files → Downloads: store files · Downloaded media is placed alongside the export output
- Side Panel → Media Files: single download · Panel can trigger individual media downloads
- Manifest → Side Panel: declares · Manifest wires the side panel entrypoint
- Manifest → Background SW: declares · Manifest wires the background service worker
- Manifest → Offscreen Doc: declares · Manifest wires the offscreen document entrypoint
- Shared Types → Side Panel: shared contract · Shared interfaces shape panel state and messages
- Shared Types → Background SW: shared contract · Shared interfaces shape orchestration messages and tree state
- Shared Types → Offscreen Doc: shared contract · Shared interfaces shape parsing messages and outputs
- Vite Build → Manifest: packages · Build pipeline emits the extension bundle and assets
