# jeffminim/romanizeme architecture

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

- Interactive diagram: https://gitdiagram.com/jeffminim/romanizeme
- Repository: https://github.com/jeffminim/romanizeme

## Overview

##### Project type and purpose
- This is a full-stack browser extension (built with Plasmo, React, TypeScript) whose purpose is to romanize non-Latin scripts on arbitrary web pages.
- The extension offers a popup UI for settings and language selection, a background script for orchestration, and content scripts that manipulate the DOM and perform text conversion using modular converter functions.

##### File structure
- Top-level:
- background.ts – background service worker
- popup.tsx – the extension’s popup UI entry
- contents/ – content scripts and conversion logic
- components/ & core/ – shared UI components (React), including panels and buttons
- hooks/, lib/, types/ – utility functions, custom hooks, type definitions
- locales/ – i18n JSON message bundles
- configuration (tsconfig.json, postcss.config.js, tailwind.config.ts)
- Architectural pattern:
- MVC-like separation between UI (components), logic (hooks, core), and data (settings, i18n)
- Modular converter functions in contents/converter for each script/language

##### README for additional insights
- Confirms React+Plasmo refactor in v2.0.0, i18n support, Toast notifications, settings panels, and optimized conversion algorithm (contents/process-texts.ts, readability-parser.ts).
- Lists supported scripts and roadmap, indicating an extensible plugin-style converter architecture.

##### Main components and their interactions
a. UI Layer
- Popup UI (popup.tsx)
- React component library (components/ui, core panels)
- Settings panel (core/settings)
- Toast notifications (components/ui/toast, sonner)
b. Background Service
- background.ts – handles message routing between UI and content scripts, manages persistent settings (browser.storage)
c. Content Scripts
- contents/convert-page.ts & restore-page.ts – entry points injected into web pages
- contents/scan-texts.ts, text-segmenter.ts, readability-parser.ts – DOM scanning & segmentation
- contents/converter/*.ts – per-language conversion logic
- contents/process-texts.ts – orchestration of scanning + conversion + injection of <ruby> annotations
d. Data & Storage
- Settings (core/settings/*) stored via browser.storage APIs
- i18n messages (locales/*) used by hooks/useI18n.ts
- lib/utils.ts, lib/version.ts – shared utilities
e. External Dependencies
- Pinyin-Pro library (for Chinese conversion)
- Browser APIs (storage, tabs, scripting, runtime messaging)

##### Architectural patterns and design principles
- Modular Converter Registry: each script’s converter is a separate module imported dynamically
- Single-page React UI in popup, following component hierarchy
- Message-based communication: UI ↔ background ↔ content scripts
- Separation of concerns: UI components vs. logic hooks vs. low-level DOM processing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Extension Frontend
    subgraph "Extension Frontend"
        direction TB
        Popup["Popup UI"]:::frontend
        UIlib["UI Component Library"]:::frontend
        CorePanels["Core Panels"]:::frontend
        ToastInPopup["Toast Notifications (Popup)"]:::frontend
    end

    %% Extension Backend
    subgraph "Extension Backend"
        direction TB
        Background["Background Service"]:::backend
        Storage["Settings Storage"]:::external
    end

    %% Content Script Context
    subgraph "Content Script Context"
        direction TB
        ConvertEntry["Convert Page Entry"]:::content
        RestoreEntry["Restore Page Entry"]:::content
        ScanTexts["Text Scanning"]:::content
        Segmenter["Text Segmentation"]:::content
        Readability["Readability Parsing"]:::content
        ProcessTexts["Conversion Orchestration"]:::content

        subgraph "Conversion Engine"
            direction TB
            ConverterIndex["Converter Registry"]:::content
            ArArabic["ar-arabic.ts"]:::content
            JpRomaji["jp-romaji.ts"]:::content
            ZhPinyin["zh-mandarin-pinyin.ts"]:::content
        end

        ToastInPage["Toast UI (In-Page)"]:::content
    end

    %% Shared Utilities & Subsystems
    subgraph "Shared Subsystems"
        direction TB
        I18n["i18n Subsystem"]:::util
        Utils["Utilities & Versioning"]:::util
        Types["Type Definitions"]:::util
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        BrowserAPIs["Browser APIs"]:::external
        PinyinPro["Pinyin-Pro Library"]:::external
    end

    %% Interactions
    Popup -->|"sendMessage"| Background
    Background -->|"executeScript"| ConvertEntry
    Background -->|"executeScript"| RestoreEntry
    ConvertEntry --> ScanTexts
    ScanTexts --> Segmenter
    Segmenter --> Readability
    Readability --> ProcessTexts
    ProcessTexts --> ConverterIndex
    ConverterIndex --> ArArabic
    ConverterIndex --> JpRomaji
    ConverterIndex --> ZhPinyin
    ProcessTexts -->|"inject <ruby>"| ConvertEntry
    ProcessTexts --> ToastInPage
    RestoreEntry -->|"restore DOM"| ConvertEntry

    Popup -->|"reads/writes"| Storage
    Background -->|"reads/writes"| Storage
    Popup --> I18n
    UIlib --> I18n
    ProcessTexts --> PinyinPro
    Background --> BrowserAPIs
    ConvertEntry --> BrowserAPIs

    %% Click Events
    click Popup "https://github.com/jeffminim/romanizeme/blob/main/popup.tsx"
    click Background "https://github.com/jeffminim/romanizeme/blob/main/background.ts"
    click ConvertEntry "https://github.com/jeffminim/romanizeme/blob/main/contents/convert-page.ts"
    click RestoreEntry "https://github.com/jeffminim/romanizeme/blob/main/contents/restore-page.ts"
    click ScanTexts "https://github.com/jeffminim/romanizeme/blob/main/contents/scan-texts.ts"
    click Segmenter "https://github.com/jeffminim/romanizeme/blob/main/contents/text-segmenter.ts"
    click Readability "https://github.com/jeffminim/romanizeme/blob/main/contents/readability-parser.ts"
    click ProcessTexts "https://github.com/jeffminim/romanizeme/blob/main/contents/process-texts.ts"
    click ConverterIndex "https://github.com/jeffminim/romanizeme/blob/main/contents/converter/index.ts"
    click ArArabic "https://github.com/jeffminim/romanizeme/blob/main/contents/converter/ar-arabic.ts"
    click JpRomaji "https://github.com/jeffminim/romanizeme/blob/main/contents/converter/jp-romaji.ts"
    click ZhPinyin "https://github.com/jeffminim/romanizeme/blob/main/contents/converter/zh-mandarin-pinyin.ts"
    click UIlib "https://github.com/jeffminim/romanizeme/tree/main/components/ui"
    click CorePanels "https://github.com/jeffminim/romanizeme/tree/main/core"
    click ToastInPopup "https://github.com/jeffminim/romanizeme/blob/main/components/ui/toast.tsx"
    click ToastInPopup "https://github.com/jeffminim/romanizeme/blob/main/components/ui/toaster.tsx"
    click I18n "https://github.com/jeffminim/romanizeme/blob/main/hooks/useI18n.ts"
    click Utils "https://github.com/jeffminim/romanizeme/blob/main/lib/utils.ts"
    click Utils "https://github.com/jeffminim/romanizeme/blob/main/lib/version.ts"
    click Types "https://github.com/jeffminim/romanizeme/blob/main/types/conversion-status.ts"
    click Types "https://github.com/jeffminim/romanizeme/blob/main/types/languages.ts"
    click Types "https://github.com/jeffminim/romanizeme/blob/main/types/settings-component.ts"
    click Types "https://github.com/jeffminim/romanizeme/blob/main/types/settings.ts"
    click Types "https://github.com/jeffminim/romanizeme/blob/main/types/text-segmentation.ts"
    click Types "https://github.com/jeffminim/romanizeme/blob/main/types/toast.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#D0FFD0,stroke:#228B22,color:#228B22;
    classDef content fill:#FFE8A0,stroke:#e69f00,color:#e69f00;
    classDef util fill:#E8E8FF,stroke:#6A5ACD,color:#6A5ACD;
    classDef external fill:#F0F0F0,stroke:#888888,color:#666666;
```
