# mengxi-ream/read-frog architecture

> Architecture diagram of the GitHub repository mengxi-ream/read-frog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mengxi-ream/read-frog
- Repository: https://github.com/mengxi-ream/read-frog

## Overview

##### Project type and purpose
- This is a browser extension (Chrome, Edge, Firefox) named “Read Frog” for immersive language learning.
- It injects UI into pages (side.content, host.content), provides a popup UI, an options page, and runs a background script to orchestrate API calls, storage, and content extraction.

##### File structure
- Top-level entrypoints folder maps directly to extension components:
- background – service worker logic (index.ts, translation, new-user guide)
- side.content & host.content – content scripts that mount React UIs on the page
- popup – React UI for toolbar popup
- options – React UI for extension settings
- guide.content – in-page onboarding guide
- src/components, src/hooks, src/utils, src/types: shared React components, hooks, utility functions, type definitions.
- config files for bundler (wxt.config.ts), linter, testing (vitest).
- package.json & pnpm-lock through pnpm, changeset-driven releases, husky + commitlint, GitHub Actions for CI/CD.

##### README for additional insights
- Features: immersive translation, content extraction, multi-model support.
- Build commands: pnpm dev, pnpm zip, pnpm zip:firefox.

a. Main components:
- Extension Manifest (implicit)
- Background Service Worker
- Content Scripts
– side.content (injected sidebar UI)
– host.content (injected translation nodes)
– guide.content (onboarding overlay)
- UI Pages (Popup, Options)
- Storage Layer (browser.storage via utils/atoms/storage-adapter)
- External AI APIs (OpenAI, DeepSeek)
- Shared Libraries (React components, hooks, utils)
b. Relationships & data flow:
1. User interacts with Popup or Options → sends messages to Background.
2. Background loads/saves config to Storage.
3. Content Scripts detect page content → send extraction/translation requests to Background.
4. Background performs API calls (requests.ts) → returns results.
5. Content Scripts render translations via injected React components.
6. guide.content reads config from Background to show onboarding.
c. Architectural patterns:
- Message-based architecture between Background ↔ Content Scripts ↔ UI pages.
- Atomic design for UI (src/components/ui).
- Separation of concerns: extraction (host/dom), translation logic (utils/host/translate.ts), configuration + migration (utils/config).
d. Key technologies:
- TypeScript + React (TSX entrypoints)
- Tailwind CSS (postcss.config.cjs + utils/tailwind)
- pnpm + Changesets for releases
- Vitest for unit tests
- GitHub Actions for CI (lint, test, release)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Manifest
    Manifest["Extension Manifest"]:::bg

    %% Entrypoints
    subgraph "Entrypoints"
        subgraph "Background Service Worker"
            BG["Background Worker"]:::bg
        end
        subgraph "Content Scripts"
            SC["Side Content Script"]:::ui
            HC["Host Content Script"]:::ui
            GC["Guide Content Script"]:::ui
        end
        subgraph "UI Pages"
            POPUP["Popup UI"]:::ui
            OPT["Options Page UI"]:::ui
        end
    end

    %% Shared Modules
    subgraph "Shared Modules"
        SH_COMP["Shared React Components"]:::shared
        SH_HOOKS["Shared Hooks"]:::shared
        SH_TYPES["Type Definitions"]:::shared
    end

    %% Utils & Logic
    subgraph "Utilities & Logic"
        STORAGE["Storage Layer Adapter"]:::bg
        MSG["Message Utilities"]:::shared
        EXTRACT["Content Extraction Logic"]:::shared
        TRANSL["Translation Logic"]:::shared
        CONFIG["Configuration & Migration"]:::shared
        REQ["External API Request Module"]:::bg
        TAIL["Tailwind & Styling Utilities"]:::shared
    end

    %% Storage and External Services
    DB["Browser.storage"]:::bg
    EXT_API["External AI Services"]:::external

    %% Build & CI/CD
    subgraph "Build & CI/CD"
        WXT["Bundler Config"]:::build
        TEST["Testing Setup"]:::build
        LINT["Linting & Hooks"]:::build
        CI["CI/CD Workflows"]:::build
    end

    %% Relationships
    Manifest --> BG
    Manifest --> SC
    Manifest --> HC
    Manifest --> GC
    Manifest --> POPUP
    Manifest --> OPT

    POPUP -->|"sendMessage"| BG
    OPT   -->|"sendMessage"| BG
    SC    -->|"sendMessage"| BG
    HC    -->|"sendMessage"| BG
    GC    -->|"sendMessage"| BG

    BG -->|"uses storage API"| DB
    OPT -->|"uses storage API"| DB

    BG -->|"calls APIs"| EXT_API

    SC --> SH_COMP
    SC --> SH_HOOKS
    HC --> SH_COMP
    HC --> SH_HOOKS
    POPUP --> SH_COMP
    POPUP --> SH_HOOKS
    OPT --> SH_COMP
    OPT --> SH_HOOKS
    GC --> SH_COMP
    GC --> SH_HOOKS

    HC --> EXTRACT
    EXTRACT --> BG

    BG --> TRANSL
    TRANSL --> REQ

    OPT --> CONFIG
    BG   --> CONFIG
    GC   --> CONFIG

    %% Build pipeline
    Manifest --- WXT
    WXT --- TEST
    TEST --- LINT
    LINT --- CI

    %% Click Events
    click BG "https://github.com/mengxi-ream/read-frog/tree/main/src/entrypoints/background"
    click SC "https://github.com/mengxi-ream/read-frog/blob/main/src/entrypoints/side.content"
    click HC "https://github.com/mengxi-ream/read-frog/blob/main/src/entrypoints/host.content"
    click GC "https://github.com/mengxi-ream/read-frog/blob/main/src/entrypoints/guide.content"
    click POPUP "https://github.com/mengxi-ream/read-frog/tree/main/src/entrypoints/popup"
    click OPT "https://github.com/mengxi-ream/read-frog/tree/main/src/entrypoints/options"
    click STORAGE "https://github.com/mengxi-ream/read-frog/blob/main/src/utils/atoms/storage-adapter.ts"
    click MSG "https://github.com/mengxi-ream/read-frog/blob/main/src/utils/message.ts"
    click REQ "https://github.com/mengxi-ream/read-frog/blob/main/src/utils/requests.ts"
    click EXTRACT "https://github.com/mengxi-ream/read-frog/tree/main/src/utils/host/dom"
    click TRANSL "https://github.com/mengxi-ream/read-frog/blob/main/src/utils/host/translate.ts"
    click CONFIG "https://github.com/mengxi-ream/read-frog/tree/main/src/utils/config"
    click SH_COMP "https://github.com/mengxi-ream/read-frog/tree/main/src/components"
    click SH_HOOKS "https://github.com/mengxi-ream/read-frog/tree/main/src/hooks"
    click SH_TYPES "https://github.com/mengxi-ream/read-frog/tree/main/src/types"
    click TAIL "https://github.com/mengxi-ream/read-frog/blob/main/src/utils/tailwind.ts"
    click WXT "https://github.com/mengxi-ream/read-frog/blob/main/wxt.config.ts"
    click TEST "https://github.com/mengxi-ream/read-frog/blob/main/vitest.config.ts"
    click LINT "https://github.com/mengxi-ream/read-frog/blob/main/eslint.config.mjs"
    click CI "https://github.com/mengxi-ream/read-frog/tree/main/.github/workflows"

    %% Styles
    classDef ui fill:#fef3c7,stroke:#d97706
    classDef bg fill:#bfdbfe,stroke:#1e40af
    classDef external fill:#d1fae5,stroke:#047857
    classDef shared fill:#e5e7eb,stroke:#6b7280
    classDef build fill:#fee2e2,stroke:#b91c1c
```
