# mattimaxforce/pdfcraft-chrome architecture

> Architecture diagram of the GitHub repository mattimaxforce/pdfcraft-chrome, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mattimaxforce/pdfcraft-chrome
- Repository: https://github.com/mattimaxforce/pdfcraft-chrome

## Overview

PdfCraft for Chrome is a local-first Chrome extension that routes PDFs into the upstream PdfCraft reader/editor. The main workflow detects or receives a PDF, opens the viewer wrapper, fetches the document, and hands it to the embedded app; saved output returns through Chrome downloads. The graph also shows settings, manual opening, and the native-viewer escape hatch. The app is generated upstream and is not present in this repository, so its internal capabilities are represented as one external component.

Main entry points: [`extension/background.js`](https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/background.js) (PDF detection and routing), [`extension/viewer/viewer.js`](https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/viewer/viewer.js) (Viewer wrapper), [`extension/popup.js`](https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/popup.js) (Settings popup), [`extension/badge.js`](https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/badge.js) (Open with badge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routing["PDF routing"]
  node_background["PDF detection and routing<br/>[background.js]"]
  node_redirect["URL redirect rules<br/>[background.js]"]
  node_content_detection["Content-Type detection<br/>[background.js]"]
  node_download_detection["Downloaded PDF handling<br/>[background.js]"]
end

subgraph group_interface["Extension interface"]
  node_context_menu["Context menu<br/>[background.js]"]
  node_badge["Open with badge<br/>[badge.js]"]
  node_popup["Settings popup<br/>[popup.js]"]
  node_locales["English and Italian strings"]
end

subgraph group_document["Document handling"]
  node_viewer["Viewer wrapper<br/>[viewer.js]"]
  node_pdf_fetch["Cookie-authenticated PDF fetch<br/>[viewer.js]"]
  node_pdfcraft["PdfCraft reader and editor"]
end

subgraph group_platform["Chrome platform"]
  node_sync_settings[("Sync settings")]
  node_session_state[("Session bypass and PDF tabs")]
  node_saved_files[("Saved PDF downloads")]
end

node_user(("PDF user"))
node_pdf_source["PDF page or link"]
node_chrome["Chrome browser APIs"]

node_user -->|"opens"| node_pdf_source
node_pdf_source -->|"triggers detection"| node_background
node_background -->|"configures"| node_redirect
node_background -->|"checks headers"| node_content_detection
node_background -->|"checks downloads"| node_download_detection
node_background -->|"registers menus"| node_context_menu
node_context_menu -->|"opens PDF"| node_viewer
node_background -->|"opens detected PDF"| node_viewer
node_background -->|"injects"| node_badge
node_badge -->|"requests opening"| node_background
node_user -->|"changes settings"| node_popup
node_popup -->|"reads and writes"| node_sync_settings
node_background -->|"reads settings"| node_sync_settings
node_background -->|"tracks bypass and tabs"| node_session_state
node_popup -->|"requests native viewer"| node_background
node_background -->|"redirects and opens tabs"| node_chrome
node_download_detection -->|"opens downloaded PDF"| node_viewer
node_viewer -->|"fetches document"| node_pdf_fetch
node_viewer -->|"sends bytes by message"| node_pdfcraft
node_pdfcraft -->|"returns saved files"| node_viewer
node_viewer -->|"downloads edited PDF"| node_saved_files
node_popup -->|"loads strings"| node_locales
node_badge -->|"loads strings"| node_locales
node_viewer -->|"loads strings"| node_locales

click node_background "https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/background.js"
click node_redirect "https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/background.js"
click node_content_detection "https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/background.js"
click node_download_detection "https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/background.js"
click node_context_menu "https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/background.js"
click node_badge "https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/badge.js"
click node_popup "https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/popup.js"
click node_locales "https://github.com/mattimaxforce/pdfcraft-chrome/tree/main/extension/_locales"
click node_viewer "https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/viewer/viewer.js"
click node_pdf_fetch "https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/viewer/viewer.js"

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_background,node_redirect,node_content_detection,node_download_detection,node_user,node_chrome toneBlue
class node_context_menu,node_badge,node_popup,node_locales toneAmber
class node_viewer,node_pdf_fetch,node_pdfcraft toneMint
class node_sync_settings,node_session_state,node_saved_files toneRose
class node_pdf_source toneIndigo
```

## Components

### PDF routing

- [PDF detection and routing](https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/background.js): `extension/background.js`
- [URL redirect rules](https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/background.js): `extension/background.js`
- [Content-Type detection](https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/background.js): `extension/background.js`
- [Downloaded PDF handling](https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/background.js): `extension/background.js`

### Extension interface

- [Context menu](https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/background.js): `extension/background.js`
- [Open with badge](https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/badge.js): `extension/badge.js`
- [Settings popup](https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/popup.js): `extension/popup.js`
- [English and Italian strings](https://github.com/mattimaxforce/pdfcraft-chrome/tree/main/extension/_locales): `extension/_locales`

### Document handling

- [Viewer wrapper](https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/viewer/viewer.js): `extension/viewer/viewer.js`
- [Cookie-authenticated PDF fetch](https://github.com/mattimaxforce/pdfcraft-chrome/blob/main/extension/viewer/viewer.js): `extension/viewer/viewer.js`
- **PdfCraft reader and editor**

### Chrome platform

- **Sync settings**
- **Session bypass and PDF tabs**
- **Saved PDF downloads**

### Other components

- **PDF user**
- **PDF page or link**
- **Chrome browser APIs**

## Connections

- PDF user → PDF page or link: opens (evidence: `README.md`)
- PDF page or link → PDF detection and routing: triggers detection (evidence: `README.md`)
- PDF detection and routing → URL redirect rules: configures (evidence: `extension/background.js`)
- PDF detection and routing → Content-Type detection: checks headers (evidence: `extension/background.js`)
- PDF detection and routing → Downloaded PDF handling: checks downloads (evidence: `extension/background.js`)
- PDF detection and routing → Context menu: registers menus (evidence: `extension/background.js`)
- Context menu → Viewer wrapper: opens PDF (evidence: `extension/background.js`)
- PDF detection and routing → Viewer wrapper: opens detected PDF (evidence: `extension/background.js`)
- PDF detection and routing → Open with badge: injects (evidence: `extension/background.js`)
- Open with badge → PDF detection and routing: requests opening (evidence: `extension/badge.js`)
- PDF user → Settings popup: changes settings (evidence: `README.md`)
- Settings popup → Sync settings: reads and writes (evidence: `extension/popup.js`)
- PDF detection and routing → Sync settings: reads settings (evidence: `extension/background.js`)
- PDF detection and routing → Session bypass and PDF tabs: tracks bypass and tabs (evidence: `extension/background.js`)
- Settings popup → PDF detection and routing: requests native viewer (evidence: `extension/popup.js`)
- PDF detection and routing → Chrome browser APIs: redirects and opens tabs (evidence: `extension/background.js`)
- Downloaded PDF handling → Viewer wrapper: opens downloaded PDF (evidence: `extension/background.js`)
- Viewer wrapper → Cookie-authenticated PDF fetch: fetches document (evidence: `extension/viewer/viewer.js`)
- Viewer wrapper → PdfCraft reader and editor: sends bytes by message (evidence: `README.md`)
- PdfCraft reader and editor → Viewer wrapper: returns saved files (evidence: `README.md`)
- Viewer wrapper → Saved PDF downloads: downloads edited PDF (evidence: `extension/viewer/viewer.js`)
- Settings popup → English and Italian strings: loads strings (evidence: `extension/popup.js`)
- Open with badge → English and Italian strings: loads strings (evidence: `extension/badge.js`)
- Viewer wrapper → English and Italian strings: loads strings (evidence: `extension/viewer/viewer.js`)