# nubplayz/goodlib-zlib-goodreads-extension architecture

> Architecture diagram of the GitHub repository nubplayz/goodlib-zlib-goodreads-extension, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nubplayz/goodlib-zlib-goodreads-extension
- Repository: https://github.com/nubplayz/goodlib-zlib-goodreads-extension

## Overview

GoodLib is a Manifest V3 browser extension built with Plasmo, TypeScript, React, and Anime.js. Architecturally, it is a small, client-side-only extension with four main runtime surfaces:

1. A background service worker
2. A content script injected into supported book pages
3. A popup UI for quick source toggles
4. An options page for persistent configuration

There is no backend in this repo. All behavior happens in the browser, and the only persisted state is local extension storage for user preferences.

#### High-level purpose

The extension enhances Goodreads and Hardcover book pages by injecting badges/links that let the user open search results on external book sources:
- Anna’s Archive
- Z-Library
- Project Gutenberg

The data flow is straightforward:
- The content script runs only on supported book-page URLs.
- It reads page context such as the displayed book title/metadata.
- It uses the current source-toggle settings to decide which badges to render.
- Clicking a badge opens the corresponding external source URL in the browser.

#### Main subsystems

##### 1. Content script subsystem
Files:
- `content.ts`
- `content.css`

This is the page-integrated layer. It is responsible for:
- Detecting supported book pages
- Reading the page’s book details
- Injecting UI elements directly into Goodreads/Hardcover pages
- Applying the associated styling via `content.css`

This is the main “in-page” boundary of the extension. It interacts with host websites’ DOM, so it is isolated from the extension’s internal UI surfaces.

##### 2. Extension background subsystem
File:
- `background.ts`

This is the service-worker layer typical of MV3 extensions. In this repo, it is the natural place for:
- Shared orchestration logic
- Messaging between popup/options/content scripts
- Reading and writing extension storage
- Centralizing source enable/disable preferences or other cross-surface state

It acts as the bridge between the browser UI surfaces and the content script that modifies book pages.

##### 3. Popup UI subsystem
Files:
- `popup.tsx`
- `popup.css`

This is the lightweight extension-action UI. Based on the README, its purpose is to let users quickly toggle which sources are active, for example:
- show only Anna’s Archive and Z-Library
- hide Project Gutenberg

This UI is React-based and likely uses extension messaging/storage to update preferences immediately. It is optimized for quick access rather than deep configuration.

##### 4. Options UI subsystem
Files:
- `options.tsx`
- `options.css`

This is the settings page for the extension. It likely provides the same preference controls as the popup, but in a more persistent and full-page form. In extension architecture terms, this is the “configuration surface” for settings that must survive browser restarts.

##### 5. Shared assets and type support
Files:
- `assets/`
- `global.d.ts`

`assets/` contains packaged static resources such as the extension icon and other visual assets referenced by the UI or manifest.

`global.d.ts` indicates shared type declarations for the TypeScript build, likely used to satisfy Plasmo/browser-extension globals and shared module typings.

#### Important architectural boundaries

##### Extension-internal vs host-page boundary
The biggest boundary is between the extension and the websites it augments:
- Host pages: Goodreads and Hardcover book pages
- Extension code: content script, popup, options, background

Only the content script touches the host page DOM. The popup and options pages do not modify the site directly; they communicate through extension APIs.

##### UI vs logic boundary
The repo separates presentation from behavior:
- `.tsx` files: React UI surfaces (`popup.tsx`, `options.tsx`)
- `.ts` files: browser/extension logic (`background.ts`, `content.ts`)

CSS is kept alongside each surface, which makes the architecture easy to map:
- `content.css` for injected page UI
- `popup.css` for the extension popup
- `options.css` for the options page

##### Persistent state boundary
User preferences are stored locally using the extension storage permission. The README explicitly says the extension stores only source toggle preferences locally and collects/transmits no user data.

That means the persistent state is limited to:
- enabled/disabled sources
- possibly any future preferences added through the options page

#### Data flow

A typical end-to-end flow looks like this:

1. User opens a Goodreads or Hardcover book page.
2. The content script activates because the URL matches the supported patterns.
3. The script extracts the book title or relevant metadata from the page.
4. It consults stored preferences to determine which sources are enabled.
5. It renders source badges directly into the page.
6. A click on a badge sends the user to the corresponding external source search/result page.

A second flow concerns settings:
1. User opens the popup or options page.
2. The React UI shows source toggle controls.
3. The user changes preferences.
4. The new settings are stored locally.
5. The content script uses those settings the next time it renders badges, and possibly updates live via messaging.

#### Technologies and how they shape the architecture

##### Plasmo 0.90.5
Plasmo provides the MV3 extension scaffolding and entry-point conventions. This is why the repository is organized around named files like `background.ts`, `content.ts`, `popup.tsx`, and `options.tsx` rather than a custom build pipeline.

##### TypeScript 5.3.3
TypeScript is used across the extension, which implies:
- shared typing between surfaces
- safer message/storage contracts
- clearer separation of concerns for browser APIs

##### React
Only the popup surface is explicitly called out as React in the README, which suggests the richer UI is implemented there, while the content script may be more DOM-oriented.

##### Anime.js v4
The README mentions animated UI. This affects the user-facing surfaces, likely the injected badges or popup interactions, but it does not change the core data flow.

##### MV3 for Chrome and Firefox
This is a browser extension architecture, not a web app or server app. The presence of MV3 means:
- background logic runs as a service worker
- page interaction happens through content scripts
- permissions are declarative and host-scoped

#### Repository-level deployment/tooling

- `package.json`, `pnpm-lock.yaml`, `package-lock.json`: package management and dependency locking
- `.github/workflows/submit.yml`: automation for submission/release-related tasks, likely tied to extension publishing
- `.prettierrc.mjs`: formatting
- `tsconfig.json`: TypeScript build configuration
- `.gitignore`: standard repo hygiene

#### Summary architecture

At a diagram level, GoodLib should be drawn as:

- A browser extension shell built with Plasmo/MV3
- One content-script lane into Goodreads/Hardcover pages
- One background service worker coordinating state and messaging
- Two extension UI surfaces: popup and options
- Local-only storage for source toggles
- External navigation targets for Anna’s Archive, Z-Library, and Project Gutenberg

The key architectural idea is that the extension does not scrape or proxy through a server. It reads page context in the browser, combines it with local preferences, and renders links that take the user directly to external source pages.

Main entry points: [`content.ts`](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/content.ts) (Content script), [`background.ts`](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/background.ts) (Background), [`popup.tsx`](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/popup.tsx) (Popup), [`options.tsx`](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/options.tsx) (Options)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Extension runtime"
  background["Background<br/>service worker<br/>[background.ts]"]
  content["Content script<br/>page injector<br/>[content.ts]"]
  content_css["Content styles<br/>injected css<br/>[content.css]"]
  storage[("Local prefs<br/>extension storage")]
end

subgraph "Extension UI"
  popup["Popup<br/>react ui<br/>[popup.tsx]"]
  popup_css["Popup styles<br/>ui css<br/>[popup.css]"]
  options["Options<br/>settings page<br/>[options.tsx]"]
  options_css["Options styles<br/>ui css<br/>[options.css]"]
  ui_state["Source toggles<br/>shared settings"]
end

subgraph "Shared assets"
  assets["Assets"]
  types["Globals<br/>type declarations<br/>[global.d.ts]"]
end

subgraph "Tooling"
  plasmo["Plasmo MV3<br/>framework<br/>[package.json]"]
  github["Workflow<br/>automation<br/>[submit.yml]"]
  tsconfig["TypeScript config<br/>build config<br/>[tsconfig.json]"]
  prettier["Format config<br/>tool config<br/>[.prettierrc.mjs]"]
end

repo{{"GoodLib<br/>mv3 extension"}}
goodreads(("Goodreads<br/>host site"))
hardcover(("Hardcover<br/>host site"))
sources(("Book sources<br/>external targets"))

repo -->|"built with"| plasmo
repo -->|"contains"| background
repo -->|"contains"| content
repo -->|"contains"| popup
repo -->|"contains"| options
background -->|"reads/writes"| storage
popup -->|"edits"| ui_state
options -->|"edits"| ui_state
ui_state -->|"persists to"| storage
content -->|"consults"| ui_state
content -->|"injects into"| goodreads
content -->|"injects into"| hardcover
content -->|"opens links"| sources
content -->|"styles with"| content_css
popup -->|"styles with"| popup_css
options -->|"styles with"| options_css
background -.->|"messages"| popup
background -.->|"messages"| options
background -.->|"messages"| content
repo -->|"bundles"| assets
repo -->|"uses"| types
repo -->|"automated by"| github
repo -->|"configured by"| tsconfig
repo -->|"formatted by"| prettier

click plasmo "https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/main/package.json"
click background "https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/main/background.ts"
click content "https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/main/content.ts"
click content_css "https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/main/content.css"
click popup "https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/main/popup.tsx"
click popup_css "https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/main/popup.css"
click options "https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/main/options.tsx"
click options_css "https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/main/options.css"
click assets "https://github.com/nubplayz/goodlib-zlib-goodreads-extension/tree/main/assets"
click types "https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/main/global.d.ts"
click github "https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/main/.github/workflows/submit.yml"
click tsconfig "https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/main/tsconfig.json"
click prettier "https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/main/.prettierrc.mjs"

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 background,content,content_css,storage toneBlue
class popup,popup_css,options,options_css,ui_state toneAmber
class assets,types toneMint
class plasmo,github,tsconfig,prettier toneRose
class repo,goodreads,hardcover,sources toneNeutral
```

## Components

### Extension runtime

Browser-executed MV3 surfaces and the local state they share.

- [Background](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/background.ts): service worker · Central extension worker for shared orchestration, messaging, and storage coordination. · `background.ts`
- [Content script](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/content.ts): page injector · Detects supported book pages, reads page context, and injects source badges into the host DOM. · `content.ts`
- [Content styles](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/content.css): injected css · Styling for the badges and page-integrated UI injected by the content script. · `content.css`
- **Local prefs**: extension storage · Persisted source-toggle preferences stored locally in the browser.

### Extension UI

User-facing surfaces for quick toggles and persistent settings.

- [Popup](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/popup.tsx): react ui · Quick extension-action UI for toggling which sources are active. · `popup.tsx`
- [Popup styles](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/popup.css): ui css · Styling for the popup surface. · `popup.css`
- [Options](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/options.tsx): settings page · Persistent configuration page for source and preference controls. · `options.tsx`
- [Options styles](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/options.css): ui css · Styling for the options surface. · `options.css`
- **Source toggles**: shared settings · Enabled/disabled source selections shared by popup, options, and content rendering.

### Shared assets

Static assets and type declarations used across the extension.

- [Assets](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/tree/HEAD/assets): static assets · Packaged icons and other static resources referenced by the extension. · `assets`
- [Globals](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/global.d.ts): type declarations · Shared TypeScript declarations for browser/Plasmo globals. · `global.d.ts`

### Tooling

Repository-level build, formatting, and release automation.

- [Plasmo MV3](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/package.json): framework · Extension scaffolding and entry-point conventions for the browser surfaces. · `package.json`
- [Workflow](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/.github/workflows/submit.yml): automation · Repository automation for submission or release-related tasks. · `.github/workflows/submit.yml`
- [TypeScript config](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/tsconfig.json): build config · TypeScript compiler and project configuration. · `tsconfig.json`
- [Format config](https://github.com/nubplayz/goodlib-zlib-goodreads-extension/blob/HEAD/.prettierrc.mjs): tool config · Repository formatting configuration. · `.prettierrc.mjs`

### Other components

- **GoodLib**: mv3 extension · Client-side browser extension that injects book-source links into supported reading sites.
- **Goodreads**: host site · Supported host page where the extension can inject source badges.
- **Hardcover**: host site · Supported host page where the extension can inject source badges.
- **Book sources**: external targets · External destinations opened from badges: Anna’s Archive, Z-Library, and Project Gutenberg.

## Connections

- GoodLib → Plasmo MV3: built with · Repository structure follows Plasmo's extension entry-point model.
- GoodLib → Background: contains · Background service worker is one of the main runtime surfaces.
- GoodLib → Content script: contains · Content script is the page-integrated runtime surface.
- GoodLib → Popup: contains · Popup provides quick extension controls.
- GoodLib → Options: contains · Options page provides persistent settings.
- Background → Local prefs: reads/writes · Background coordinates persisted extension preferences.
- Popup → Source toggles: edits · Popup changes which book sources are enabled.
- Options → Source toggles: edits · Options page exposes the same persistent preferences.
- Source toggles → Local prefs: persists to · Source-toggle state is stored locally in extension storage.
- Content script → Source toggles: consults · Content rendering uses the current source-toggle settings.
- Content script → Goodreads: injects into · Runs on supported Goodreads pages.
- Content script → Hardcover: injects into · Runs on supported Hardcover pages.
- Content script → Book sources: opens links · Badge clicks navigate the user to external book-source pages.
- Content script → Content styles: styles with · Injected page UI is styled separately from logic.
- Popup → Popup styles: styles with · Popup presentation is kept in its own stylesheet.
- Options → Options styles: styles with · Options page presentation is kept in its own stylesheet.
- Background → Popup: messages · Background serves as a coordination point for extension UI surfaces.
- Background → Options: messages · Background can coordinate settings updates and cross-surface state.
- Background → Content script: messages · Background can relay shared state to the page-integrated script.
- GoodLib → Assets: bundles · Static assets are packaged with the extension.
- GoodLib → Globals: uses · Shared declaration file supports TypeScript compilation.
- GoodLib → Workflow: automated by · Repository includes workflow automation.
- GoodLib → TypeScript config: configured by · TypeScript compilation is defined at the repository level.
- GoodLib → Format config: formatted by · Repository formatting is defined separately.
