# ainoob/noobox architecture

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

- Interactive diagram: https://gitdiagram.com/ainoob/noobox
- Repository: https://github.com/ainoob/noobox

## Overview

1. **What this repo is**
   - NooBox is a **Chrome extension** for image-centric workflows: reverse image search, image extraction, auto-refresh, and HTML5 video control.
   - It is structured to support both **Manifest V2 and Manifest V3**, with shared base manifests and environment-specific overrides.

2. **Top-level architecture**
   - The extension is split into four main runtime surfaces:
     - **Background** logic for orchestration and browser-level actions.
     - **Content scripts** that run inside web pages and can inspect or manipulate page DOM/media.
     - **Popup UI** for user interaction and settings.
     - **Search result pages** that present aggregated reverse-image-search output in a dedicated extension tab.

3. **Primary user flows**
   - Users can start searches via multiple entry points: popup upload, drag/drop, right-click/context actions, screenshot search, or page-based image detection.
   - The request typically moves from **content script or popup → background → external search engines**, then results are shown in the search-result UI and often persisted in history.

4. **Background subsystem**
   - `src/background` is the central coordinator.
   - It contains modules for:
     - **Image search orchestration** (`imageSearch/*`)
     - **Engine tab / URL management** (`engineTabs.ts`, `engineUrls.ts`)
     - **Auto refresh** (`autoRefresh.ts`)
     - **Video control** (`videoControl.ts`)
     - **Options and messaging** (`options.ts`, `main.ts`)
   - This layer is responsible for browser-wide side effects like tab creation, navigation, and cross-context coordination.

5. **Reverse-image-search engine adapters**
   - Each supported engine has its own adapter in both background and content-script layers:
     - Bing, Google, Yandex, Baidu, TinEye, SauceNAO, IQDB, Ascii2D.
   - The background adapters implement the search workflow and result normalization; the content-script engine files provide page-specific extraction or interaction logic where needed.
   - This is a key architectural boundary: **engine-specific quirks are isolated per provider**, while higher-level UI and orchestration stay generic.

6. **Content-script responsibilities**
   - `src/contentScript` is page-local automation and extraction code.
   - It handles:
     - **Image extraction** from the current page (`extractImages.js`)
     - **Screenshot-based search** (`screenshotSearch.js`)
     - **Search-by-image interactions** (`searchByImage.ts`)
     - **Video control hooks** (`videoControl.js`)
   - Because content scripts operate inside arbitrary sites, they bridge the extension with page DOM/media without requiring the background page to inspect the webpage directly.

7. **Popup UI**
   - `src/popup` contains the extension’s primary control panel.
   - It includes:
     - Overview/dashboard
     - Upload/search entry points
     - Auto-refresh controls
     - Video control controls
     - Image search history
     - Options and about pages
   - State is handled through dedicated stores under `src/popup/stores`, which keeps UI state separate from browser orchestration logic.

8. **Search-result experience**
   - `src/searchResult` is a dedicated extension page for viewing reverse-search output.
   - It is composed of a header, action bar, engine selector, and result content area.
   - `searchResultStore` drives the page state, making it distinct from the popup: the popup is for initiating actions, while this page is for **reviewing and managing aggregated results**.

9. **Persistence and shared state**
   - `src/dao` and `src/utils/db.ts` provide IndexedDB-backed persistence.
   - The main persisted domain appears to be **image search history** and possibly related records for recall in the popup/search-result flows.
   - `src/shared/stores/optionsStore.ts` provides cross-UI access to extension options, indicating that settings are shared between popup, background, and result pages.

10. **Debugging and development support**
   - There is a small standalone `debug-server/` used in development/debug scenarios, with simple JSON/HTML storage helpers.
   - The repo also includes `src/debug/commandClient.ts`, `index.debug.ts`, and manifest debug overrides, suggesting a controlled debug mode for extension development.
   - Build/verification is handled by webpack and supporting tooling in `tools/`, with separate checks for production manifest generation.

11. **Internationalization and assets**
   - UI text is localized through `src/_locales` with English, Japanese, Simplified Chinese, and Traditional Chinese bundles.
   - Static assets such as engine logos and third-party CSS live under `src/images` and `thirdParty/`, supporting the extension UI and result presentation.

12. **Important architectural boundaries**
   - **Web page context vs extension context**: content scripts handle page access; background handles privileged browser actions.
   - **Initiation vs presentation**: popup/content scripts start work; search-result pages present aggregated outcomes.
   - **Engine-specific vs engine-agnostic logic**: each search provider has its own adapter, but the user-facing flows are unified.
   - **Persistent history vs transient search state**: IndexedDB-backed history survives sessions, while stores manage ephemeral UI state.

Main entry points: [`src/background/main.ts`](https://github.com/ainoob/noobox/blob/bello/src/background/main.ts) (Main orchestration), [`src/background/imageSearch`](https://github.com/ainoob/noobox/tree/bello/src/background/imageSearch) (Search orchestration), [`src/popup/popup.tsx`](https://github.com/ainoob/noobox/blob/bello/src/popup/popup.tsx) (Popup entry), [`src/searchResult/searchResult.tsx`](https://github.com/ainoob/noobox/blob/bello/src/searchResult/searchResult.tsx) (Result entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime surfaces"]
end

subgraph group_background["Background"]
  node_src_background_index["Background entry<br/>entrypoint<br/>[index.ts]"]
  node_src_background_main["Main orchestration<br/>coordinator<br/>[main.ts]"]
  node_src_background_image_search{{"Search orchestration<br/>workflow"}}
  node_src_background_engine_tabs["Engine tabs<br/>tab management<br/>[engineTabs.ts]"]
  node_src_background_engine_urls["Engine URLs<br/>url routing<br/>[engineUrls.ts]"]
  node_src_background_options["Options<br/>settings bridge<br/>[options.ts]"]
  node_src_background_auto_refresh["Auto refresh<br/>background feature<br/>[autoRefresh.ts]"]
  node_src_background_video_control["Video control<br/>background feature<br/>[videoControl.ts]"]
  node_src_background_google_debugger["Google debugger<br/>engine helper<br/>[googleDebugger.ts]"]
end

subgraph group_content["Content scripts"]
  node_src_content_extract_images["Extract images<br/>page extractor<br/>[extractImages.js]"]
  node_src_content_screenshot_search["Screenshot search<br/>page capture"]
  node_src_content_search_by_image["Search by image<br/>page bridge<br/>[searchByImage.ts]"]
  node_src_content_video_control["Video hooks<br/>page control<br/>[videoControl.js]"]
  node_src_content_engines{{"Engine scripts<br/>engine adapters"}}
end

subgraph group_ui["UI"]
  node_src_popup_popup["Popup entry<br/>entrypoint<br/>[popup.tsx]"]
  node_src_popup_overview["Overview<br/>dashboard<br/>[overview.tsx]"]
  node_src_popup_history["Search history<br/>ui panel"]
  node_src_popup_options["Options page<br/>ui panel<br/>[options.tsx]"]
  node_src_search_result_root["Result entry<br/>entrypoint<br/>[searchResult.tsx]"]
  node_src_search_result_content["Result content<br/>viewer<br/>[content.tsx]"]
  node_src_search_result_header["Result header<br/>controls<br/>[header.tsx]"]
  node_src_search_result_store["Result state<br/>store"]
end

subgraph group_data["Data"]
  node_src_dao_image_search[("Search history DAO<br/>persistence<br/>[imageSearchDao.ts]")]
  node_src_shared_options_store["Options store<br/>shared state<br/>[optionsStore.ts]"]
  node_src_utils_db["IndexedDB helper<br/>storage util<br/>[db.ts]"]
end

subgraph group_dev["Dev/support"]
  node_debug_server["Debug server<br/>dev service<br/>[server.js]"]
  node_src_debug_command_client["Command client<br/>debug client<br/>[commandClient.ts]"]
  node_manifest_v2_base["MV2 base<br/>manifest<br/>[base.json]"]
  node_manifest_v3_base["MV3 base<br/>manifest<br/>[base.json]"]
end

node_manifest_v2_base -->|"loads"| node_src_background_index
node_manifest_v3_base -->|"loads"| node_src_background_index
node_src_background_index -->|"starts"| node_src_background_main
node_src_background_main -->|"dispatches"| node_src_background_image_search
node_src_background_main -->|"opens tabs"| node_src_background_engine_tabs
node_src_background_main -->|"builds urls"| node_src_background_engine_urls
node_src_background_main -->|"reads options"| node_src_background_options
node_src_background_main -->|"controls"| node_src_background_auto_refresh
node_src_background_main -->|"controls"| node_src_background_video_control
node_src_background_image_search -->|"uses"| node_src_background_engine_tabs
node_src_background_image_search -->|"uses"| node_src_background_engine_urls
node_src_background_image_search -->|"persists"| node_src_dao_image_search
node_src_background_image_search -.->|"debugs"| node_src_background_google_debugger
node_src_content_search_by_image -->|"messages"| node_src_background_main
node_src_content_extract_images -->|"messages"| node_src_background_main
node_src_content_screenshot_search -->|"messages"| node_src_background_main
node_src_content_video_control -->|"syncs"| node_src_background_video_control
node_src_content_engines -->|"engine quirks"| node_src_background_image_search
node_src_popup_popup -->|"routes"| node_src_popup_overview
node_src_popup_popup -->|"routes"| node_src_popup_history
node_src_popup_popup -->|"routes"| node_src_popup_options
node_src_popup_overview -->|"starts work"| node_src_background_main
node_src_popup_overview -->|"reads"| node_src_shared_options_store
node_src_popup_history -->|"reads"| node_src_dao_image_search
node_src_search_result_root -->|"composes"| node_src_search_result_header
node_src_search_result_root -->|"composes"| node_src_search_result_content
node_src_search_result_root -->|"uses"| node_src_search_result_store
node_src_search_result_header -->|"controls"| node_src_search_result_store
node_src_search_result_content -->|"reads"| node_src_dao_image_search
node_src_search_result_content -->|"reads"| node_src_shared_options_store
node_src_shared_options_store -->|"syncs"| node_src_background_options
node_src_debug_command_client -->|"connects"| node_debug_server

click node_src_background_index "https://github.com/ainoob/noobox/blob/bello/src/background/index.ts"
click node_src_background_main "https://github.com/ainoob/noobox/blob/bello/src/background/main.ts"
click node_src_background_image_search "https://github.com/ainoob/noobox/tree/bello/src/background/imageSearch"
click node_src_background_engine_tabs "https://github.com/ainoob/noobox/blob/bello/src/background/engineTabs.ts"
click node_src_background_engine_urls "https://github.com/ainoob/noobox/blob/bello/src/background/engineUrls.ts"
click node_src_background_options "https://github.com/ainoob/noobox/blob/bello/src/background/options.ts"
click node_src_background_auto_refresh "https://github.com/ainoob/noobox/blob/bello/src/background/autoRefresh.ts"
click node_src_background_video_control "https://github.com/ainoob/noobox/blob/bello/src/background/videoControl.ts"
click node_src_background_google_debugger "https://github.com/ainoob/noobox/blob/bello/src/background/googleDebugger.ts"
click node_src_content_extract_images "https://github.com/ainoob/noobox/blob/bello/src/contentScript/extractImages.js"
click node_src_content_screenshot_search "https://github.com/ainoob/noobox/blob/bello/src/contentScript/screenshotSearch.js"
click node_src_content_search_by_image "https://github.com/ainoob/noobox/blob/bello/src/contentScript/searchByImage.ts"
click node_src_content_video_control "https://github.com/ainoob/noobox/blob/bello/src/contentScript/videoControl.js"
click node_src_content_engines "https://github.com/ainoob/noobox/tree/bello/src/contentScript/engines"
click node_src_popup_popup "https://github.com/ainoob/noobox/blob/bello/src/popup/popup.tsx"
click node_src_popup_overview "https://github.com/ainoob/noobox/blob/bello/src/popup/overview.tsx"
click node_src_popup_history "https://github.com/ainoob/noobox/blob/bello/src/popup/imageSearchHistory.tsx"
click node_src_popup_options "https://github.com/ainoob/noobox/blob/bello/src/popup/options.tsx"
click node_src_search_result_root "https://github.com/ainoob/noobox/blob/bello/src/searchResult/searchResult.tsx"
click node_src_search_result_content "https://github.com/ainoob/noobox/blob/bello/src/searchResult/content/content.tsx"
click node_src_search_result_header "https://github.com/ainoob/noobox/blob/bello/src/searchResult/header.tsx"
click node_src_search_result_store "https://github.com/ainoob/noobox/blob/bello/src/searchResult/stores/searchResultStore.ts"
click node_src_dao_image_search "https://github.com/ainoob/noobox/blob/bello/src/dao/imageSearchDao.ts"
click node_src_shared_options_store "https://github.com/ainoob/noobox/blob/bello/src/shared/stores/optionsStore.ts"
click node_src_utils_db "https://github.com/ainoob/noobox/blob/bello/src/utils/db.ts"
click node_debug_server "https://github.com/ainoob/noobox/blob/bello/debug-server/server.js"
click node_src_debug_command_client "https://github.com/ainoob/noobox/blob/bello/src/debug/commandClient.ts"
click node_manifest_v2_base "https://github.com/ainoob/noobox/blob/bello/manifest/v2/base.json"
click node_manifest_v3_base "https://github.com/ainoob/noobox/blob/bello/manifest/v3/base.json"

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_src_background_index,node_src_background_main,node_src_background_image_search,node_src_background_engine_tabs,node_src_background_engine_urls,node_src_background_options,node_src_background_auto_refresh,node_src_background_video_control,node_src_background_google_debugger toneAmber
class node_src_content_extract_images,node_src_content_screenshot_search,node_src_content_search_by_image,node_src_content_video_control,node_src_content_engines toneMint
class node_src_popup_popup,node_src_popup_overview,node_src_popup_history,node_src_popup_options,node_src_search_result_root,node_src_search_result_content,node_src_search_result_header,node_src_search_result_store toneRose
class node_src_dao_image_search,node_src_shared_options_store,node_src_utils_db toneIndigo
class node_debug_server,node_src_debug_command_client,node_manifest_v2_base,node_manifest_v3_base toneTeal
```

## Components

### Background

Privileged orchestration and browser-side coordination

- [Background entry](https://github.com/ainoob/noobox/blob/bello/src/background/index.ts): entrypoint · Wires the background runtime for MV2/MV3. · `src/background/index.ts`
- [Main orchestration](https://github.com/ainoob/noobox/blob/bello/src/background/main.ts): coordinator · Central background message handling and workflow coordination. · `src/background/main.ts`
- [Search orchestration](https://github.com/ainoob/noobox/tree/bello/src/background/imageSearch): workflow · Background image-search control flow and provider dispatch. · `src/background/imageSearch`
- [Engine tabs](https://github.com/ainoob/noobox/blob/bello/src/background/engineTabs.ts): tab management · Creates and manages tabs used by reverse-image-search engines. · `src/background/engineTabs.ts`
- [Engine URLs](https://github.com/ainoob/noobox/blob/bello/src/background/engineUrls.ts): url routing · Builds and normalizes engine-specific navigation URLs. · `src/background/engineUrls.ts`
- [Options](https://github.com/ainoob/noobox/blob/bello/src/background/options.ts): settings bridge · Background access to extension options and shared preferences. · `src/background/options.ts`
- [Auto refresh](https://github.com/ainoob/noobox/blob/bello/src/background/autoRefresh.ts): background feature · Implements page/tab auto-refresh behavior. · `src/background/autoRefresh.ts`
- [Video control](https://github.com/ainoob/noobox/blob/bello/src/background/videoControl.ts): background feature · Coordinates browser-level video control actions. · `src/background/videoControl.ts`
- [Google debugger](https://github.com/ainoob/noobox/blob/bello/src/background/googleDebugger.ts): engine helper · Engine-specific debugging support for Google flows. · `src/background/googleDebugger.ts`

### Content scripts

Page-local extraction and automation

- [Extract images](https://github.com/ainoob/noobox/blob/bello/src/contentScript/extractImages.js): page extractor · Finds images in the current page DOM. · `src/contentScript/extractImages.js`
- [Screenshot search](https://github.com/ainoob/noobox/blob/bello/src/contentScript/screenshotSearch.js): page capture · Captures page content for screenshot-based search. · `src/contentScript/screenshotSearch.js`
- [Search by image](https://github.com/ainoob/noobox/blob/bello/src/contentScript/searchByImage.ts): page bridge · Page-side entry for image search interactions. · `src/contentScript/searchByImage.ts`
- [Video hooks](https://github.com/ainoob/noobox/blob/bello/src/contentScript/videoControl.js): page control · Injects page-local video control hooks. · `src/contentScript/videoControl.js`
- [Engine scripts](https://github.com/ainoob/noobox/tree/bello/src/contentScript/engines): engine adapters · Page-specific provider logic for individual reverse-image-search engines. · `src/contentScript/engines`

### UI

Popup and dedicated result page

- [Popup entry](https://github.com/ainoob/noobox/blob/bello/src/popup/popup.tsx): entrypoint · Popup UI bootstrap and routing. · `src/popup/popup.tsx`
- [Overview](https://github.com/ainoob/noobox/blob/bello/src/popup/overview.tsx): dashboard · Primary popup surface for starting searches and quick controls. · `src/popup/overview.tsx`
- [Search history](https://github.com/ainoob/noobox/blob/bello/src/popup/imageSearchHistory.tsx): ui panel · Popup view for recalling past image searches. · `src/popup/imageSearchHistory.tsx`
- [Options page](https://github.com/ainoob/noobox/blob/bello/src/popup/options.tsx): ui panel · Popup-accessible settings surface. · `src/popup/options.tsx`
- [Result entry](https://github.com/ainoob/noobox/blob/bello/src/searchResult/searchResult.tsx): entrypoint · Bootstrap for the dedicated search-result page. · `src/searchResult/searchResult.tsx`
- [Result content](https://github.com/ainoob/noobox/blob/bello/src/searchResult/content/content.tsx): viewer · Aggregated reverse-search result presentation. · `src/searchResult/content/content.tsx`
- [Result header](https://github.com/ainoob/noobox/blob/bello/src/searchResult/header.tsx): controls · Header actions, engine selection, and result summary. · `src/searchResult/header.tsx`
- [Result state](https://github.com/ainoob/noobox/blob/bello/src/searchResult/stores/searchResultStore.ts): store · State container for the search-result page. · `src/searchResult/stores/searchResultStore.ts`

### Data

Persistence and shared state

- [Search history DAO](https://github.com/ainoob/noobox/blob/bello/src/dao/imageSearchDao.ts): persistence · IndexedDB-backed storage for image search records. · `src/dao/imageSearchDao.ts`
- [Options store](https://github.com/ainoob/noobox/blob/bello/src/shared/stores/optionsStore.ts): shared state · Cross-surface access to extension options. · `src/shared/stores/optionsStore.ts`
- [IndexedDB helper](https://github.com/ainoob/noobox/blob/bello/src/utils/db.ts): storage util · Low-level database access wrapper. · `src/utils/db.ts`

### Dev/support

Debug and build support

- [Debug server](https://github.com/ainoob/noobox/blob/bello/debug-server/server.js): dev service · Standalone development/debug backend. · `debug-server/server.js`
- [Command client](https://github.com/ainoob/noobox/blob/bello/src/debug/commandClient.ts): debug client · Client-side bridge to the debug server. · `src/debug/commandClient.ts`
- [MV2 base](https://github.com/ainoob/noobox/blob/bello/manifest/v2/base.json): manifest · Base manifest definition for Manifest V2. · `manifest/v2/base.json`
- [MV3 base](https://github.com/ainoob/noobox/blob/bello/manifest/v3/base.json): manifest · Base manifest definition for Manifest V3. · `manifest/v3/base.json`

## Connections

- MV2 base → Background entry: loads · Manifest V2 wires the extension runtime.
- MV3 base → Background entry: loads · Manifest V3 wires the extension runtime.
- Background entry → Main orchestration: starts · Background entry hands control to orchestration.
- Main orchestration → Search orchestration: dispatches · Routes reverse-image-search workflows.
- Main orchestration → Engine tabs: opens tabs · Creates and manages search-engine tabs.
- Main orchestration → Engine URLs: builds urls · Uses engine URL construction for navigation.
- Main orchestration → Options: reads options · Consumes shared extension settings.
- Main orchestration → Auto refresh: controls · Coordinates browser auto-refresh behavior.
- Main orchestration → Video control: controls · Coordinates global video control actions.
- Search orchestration → Engine tabs: uses · Search flow creates provider tabs.
- Search orchestration → Engine URLs: uses · Search flow generates provider-specific URLs.
- Search orchestration → Search history DAO: persists · Stores search history and related records.
- Search orchestration → Google debugger: debugs · Google-specific inspection support.
- Search by image → Main orchestration: messages · Page-local actions delegate to the background.
- Extract images → Main orchestration: messages · Extraction results are forwarded to background workflows.
- Screenshot search → Main orchestration: messages · Screenshot search requests are delegated.
- Video hooks → Video control: syncs · Page hooks integrate with background control logic.
- Engine scripts → Search orchestration: engine quirks · Provider-specific page automation supports search orchestration.
- Popup entry → Overview: routes · Popup bootstraps the main dashboard view.
- Popup entry → Search history: routes · Popup can open search history.
- Popup entry → Options page: routes · Popup can open settings.
- Overview → Main orchestration: starts work · Popup entry points initiate browser-side actions.
- Overview → Options store: reads · Overview uses shared settings state.
- Search history → Search history DAO: reads · History UI loads persisted search records.
- Result entry → Result header: composes · Dedicated result page includes header controls.
- Result entry → Result content: composes · Dedicated result page includes result content.
- Result entry → Result state: uses · Page state is driven by a local store.
- Result header → Result state: controls · Header actions mutate result-page state.
- Result content → Search history DAO: reads · Result management can consult persisted history.
- Result content → Options store: reads · Presentation respects shared extension options.
- Options store → Options: syncs · Options are shared across extension surfaces.
- Command client → Debug server: connects · Debug client talks to the standalone server.
