# birchill/10ten-ja-reader architecture

> Architecture diagram of the GitHub repository birchill/10ten-ja-reader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/birchill/10ten-ja-reader
- Repository: https://github.com/birchill/10ten-ja-reader

## Overview

##### Main Components
- Extension Core: The heart of the extension is split between several primary areas:
- Background Scripts (located in src/background): These manage browser events, messaging, tab management, search logic, and more. They act as the coordinator for communication between injected content scripts and other parts of the extension.
- Content Scripts (located in src/content): These are injected into web pages to capture user interactions (like hover, text selection, or copy events) and initiate dictionary lookups or text processing.
- Popup and Options UI (located in src/content/popup and src/options): These components (built using React/TypeScript) provide an interactive user interface for displaying word definitions, Kanji information, settings, and other interactive controls.
- Worker Scripts (located in src/worker): Specifically, the JP Dict worker offloads dictionary processing, ensuring that heavy computation does not interfere with the UI responsiveness.
- Localization & Data Assets:
- The _locales directory stores translation and localization files for English, Japanese, and Simplified Chinese, which are critical for the UI.
- The data directory contains pre-built dictionary files and index formats needed for fast word lookups.
- Build and Configuration Tools:
- The package.json, rspack and cosmos configuration files, and scripts folder (with various build and maintenance scripts) outline the build process and custom tasks.
- CI/CD integration is defined through several GitHub Actions workflows (.github/workflows) that manage testing, publishing, and releases.
- Native Integration:
- The xcode13 directory indicates the project also builds for Safari (and potentially iOS/macOS) using native projects, hosting both App and Extension targets.

##### Relationships and Data Flow
- The browser injects the content scripts into webpages where they detect user interactions – when activated (via mouse hover, key presses, or context menu), these scripts send messages to the background scripts.
- The background scripts process these incoming messages and, when necessary, communicate further with the worker components for dictionary lookups or language processing.
- Results are then pushed back to the UI components: either directly rendered in the in-page popup or via the options interface for configuration.
- Localization assets and theme/style resources (found in css, fonts, and images directories) are imported by the UI components to ensure consistent, localized user interface experiences.
- For the Safari-specific or cross-platform builds, the Xcode projects encapsulate both the shared extension logic and platform-specific integration, so these native components are represented as a separate “Native Integration” block that interfaces with the web-extension core.
- The build pipeline (scripts and GitHub workflows) triggers the build processes and package generation for each targeted browser and app store, integrating continuous testing (for example, through Playwright tests) and pre-publishing checks.

##### Architectural Patterns and Technologies
- Modularity and Separation of Concerns: The code is organized into clear, discrete modules (background, content, options) that communicate via message passing.
- CI/CD & Build Automation: The use of GitHub Actions and scripts emphasizes a pipeline-driven approach to releases and quality assurance.
- Cross-Platform Packaging: The inclusion of both web extension packages and native projects (via Xcode) highlights the multi-target deployment strategy.
- Use of Modern Web Technologies: The project leverages TypeScript, React/TSX (noticeable from the .tsx files in popup and options), and utilizes popular build tools (pnpm, rspack, cosmos).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Presentation Layer
    subgraph "Presentation Layer"
        PU["Popup UI"]:::ui
        OU["Options UI"]:::ui
    end

    %% Application Logic Layer
    subgraph "Application Logic Layer"
        CS["Content Script Handler (src/content)"]:::app
        BG["Background Manager (src/background)"]:::app
        WK["JP Dict Worker (src/worker)"]:::app
    end

    %% Data Layer
    subgraph "Data Layer"
        LA["Localization Assets (_locales)"]:::data
        DD["Dictionary Data (data)"]:::data
    end

    %% Build & Deployment Layer
    subgraph "Build & Deployment Layer"
        BT["Build Tools & CI/CD\n(package.json, cosmos.config.json, rspack.config.js, scripts, .github/workflows)"]:::build
    end

    %% Native Integration Layer
    subgraph "Native Integration Layer"
        NX["Xcode Projects (xcode13)"]:::native
    end

    %% Inter-layer Connections
    %% Content Scripts send messages to Background Manager
    CS -->|"sendMessage"| BG

    %% Background Manager communicates with JP Dict Worker
    BG -->|"lookup"| WK
    WK -->|"result"| BG

    %% Background Manager sends results to UI components
    BG -->|"display"| PU
    BG -->|"display"| OU

    %% Localization feeds UI for translations
    LA -->|"localize"| PU
    LA -->|"localize"| OU

    %% Dictionary data provides lookup information to the Worker
    DD -->|"dictionary"| WK

    %% Build Tools trigger build & deployment of extension core and native integration
    BT -->|"build&deploy"| CS
    BT -->|"build&deploy"| BG
    BT -->|"build&deploy"| WK
    BT -->|"build&deploy"| PU
    BT -->|"build&deploy"| OU
    BT -->|"build&deploy"| NX

    %% Native Integration obtains bundled extension logic from Background Manager
    BG -->|"nativeBundle"| NX
    NX -->|"feedback"| BG

    %% Click Events
    click BG "https://github.com/birchill/10ten-ja-reader/tree/main/src/background"
    click CS "https://github.com/birchill/10ten-ja-reader/tree/main/src/content"
    click PU "https://github.com/birchill/10ten-ja-reader/tree/main/src/content/popup"
    click OU "https://github.com/birchill/10ten-ja-reader/tree/main/src/options"
    click WK "https://github.com/birchill/10ten-ja-reader/tree/main/src/worker"
    click LA "https://github.com/birchill/10ten-ja-reader/tree/main/_locales"
    click DD "https://github.com/birchill/10ten-ja-reader/tree/main/data"
    click BT "https://github.com/birchill/10ten-ja-reader/blob/main/package.json"
    click BT "https://github.com/birchill/10ten-ja-reader/blob/main/cosmos.config.json"
    click BT "https://github.com/birchill/10ten-ja-reader/blob/main/rspack.config.js"
    click BT "https://github.com/birchill/10ten-ja-reader/tree/main/scripts"
    click BT "https://github.com/birchill/10ten-ja-reader/tree/main/.github/workflows"
    click NX "https://github.com/birchill/10ten-ja-reader/tree/main/xcode13"

    %% Styles
    classDef ui fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef app fill:#F7D6BF,stroke:#333,stroke-width:2px;
    classDef data fill:#C7F7BF,stroke:#333,stroke-width:2px;
    classDef build fill:#F7BFED,stroke:#333,stroke-width:2px;
    classDef native fill:#F7F7BF,stroke:#333,stroke-width:2px;
```
