# crimx/ext-saladict architecture

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

- Interactive diagram: https://gitdiagram.com/crimx/ext-saladict
- Repository: https://github.com/crimx/ext-saladict

## Overview

##### Project Type and Purpose
- This is a Chrome/Firefox WebExtension that enables inline translation and dictionary lookup. Its functionality spans from content manipulation on webpages (injecting translation UI components) to background processing (handling translation requests, managing settings, syncing data, and interfacing with various dictionary APIs).
- Additionally, it contains a mac-app component designed to package the extension for macOS, giving it a native feel in Apple’s ecosystem.

##### File Structure to Reveal Components
- Top-Level Directories:
- “src/background”: Contains background scripts including core logic such as audio management, badge updating, context menus, database handling, and sync management. This part of the code orchestrates translation requests, manages browser events, and performs other central functions.
- “src/content”: Includes the content scripts that are injected into web pages. They manage the in-page UI elements (e.g., dictionary panels, tooltips, word editors) and capture user interactions like text selection.
- “src/options”: Provides the configuration pages where users set preferences, manage dictionary settings, and adjust profiles. It’s a rich UI built predominantly with React components and Redux to handle state.
- “src/popup” and “src/quick-search”: These are the entry points for the user interface elements triggered within the browser toolbar. They provide quick access to translation features.
- “src/notebook” and “src/word-editor”: Additional UI pages for features like saving translations and editing words.
- “src/app-config” and “src/components/dictionaries”: Define the configuration, integration, and engine implementations for various external dictionaries (like Bing, Youdao, Cambridge, etc.). These modules encapsulate the business logic for dictionary queries.
- “mac-app”: Contains native packaging files and assets to build a macOS packaged version of the Saladict extension.
- Other directories like “assets”, “config”, “test”, ".storybook", “docs”, etc., handle styling, build tooling, testing, Storybook configurations for UI component documentation, and documentation support.

##### Architectural Components and Interactions
- Main Components to Include:
- Background Service:
◦ Modules under “src/background” for initialization, audio management, context menus, language management, and sync. Also, the submodules within “src/background/sync-manager” indicate integration with external synchronization (e.g., Ankiconnect, Eudic, Shanbay, WebDAV).
- Content Scripts:
- Options and Popup UIs:
◦ “src/options”, “src/popup”, and “src/quick-search” represent the different UI facets of the extension. They are built with React, use Redux for state management, and allow user customization.
- Dictionary Engines:
◦ The “src/app-config/dicts” and “src/components/dictionaries” directories hold a set of engines for different translation services. Each dictionary component/module has its own configs, locales, and engine logic.
- mac-app Bundle:
◦ The “mac-app” directory represents the standalone macOS packaging, which integrates with the rest of the system, using some of the same entry points but built for native execution via Xcode configurations.
- Relationships and Interactions:
- Communication flows between content scripts and background scripts via the browser’s messaging APIs. For example, user events captured in a web page trigger messages to the background which in turn invoke dictionary lookups.
- The Options and Popup UIs send requests to the background scripts when changing settings or initiating translations.
- The dictionary engine modules interact with remote translation services and provide data back through the background logic.
- The mac-app layer wraps around the primary extension logic for deployment on macOS.
- Shared libraries in “src/_helpers” and “src/app-config” are used across many components ensuring consistency (e.g., for analytics events, configuration merging, and i18n functionalities).

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project is distinctly split between background logic, content interaction, and configuration UIs. Each component has its own domain.
- Modularization: The dictionary engines are modularized allowing the system to easily add or update integration with external services.
- Message Passing: Communication between the content scripts, background scripts, and UI pages is handled via structured message passing mechanisms, commonly seen in browser extensions.
- Internationalization: There is robust support for multiple locales, as evident from the “src/_locales” and dictionary-specific locales.
- Testability: Extensive testing is provided under the “test” directory with mocks and specs for API calls and component rendering.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-Level Nodes
    User("User Browser"):::user

    %% UI Layer
    subgraph "UI Layer"
        Options("Options UI"):::ui
        Popup("Popup/Quick Search UI"):::ui
        Content("Content Scripts"):::ui
        Notebook("Notebook/Word Editor UI"):::ui
    end

    %% Background Layer
    subgraph "Background Layer"
        Background("Background Service"):::background
    end

    %% Dictionary Engines Layer
    subgraph "Dictionary Engines"
        Engines("Dictionary Engines"):::engines
    end

    %% mac-app Packaging
    subgraph "Packaging"
        Macapp("mac-app Packaging"):::macapp
    end

    %% User interactions with UI Layer
    User -->|"interacts"| Options
    User -->|"interacts"| Popup
    User -->|"interacts"| Content
    User -->|"interacts"| Notebook

    %% UI communication to Background Service
    Options -->|"send_request"| Background
    Popup -->|"send_request"| Background
    Content -->|"send_request"| Background
    Notebook -->|"send_request"| Background

    %% Background interactions with Dictionary Engines
    Background -->|"invoke_dict"| Engines
    Engines -->|"return_data"| Background

    %% mac-app Packaging integration
    Background -->|"integrates"| Macapp

    %% Click Events
    click Background "https://github.com/crimx/ext-saladict/tree/dev/src/background"
    click Content "https://github.com/crimx/ext-saladict/tree/dev/src/content"
    click Options "https://github.com/crimx/ext-saladict/tree/dev/src/options"
    click Popup "https://github.com/crimx/ext-saladict/tree/dev/src/popup"
    click Popup "https://github.com/crimx/ext-saladict/tree/dev/src/quick-search"
    click Notebook "https://github.com/crimx/ext-saladict/tree/dev/src/notebook"
    click Notebook "https://github.com/crimx/ext-saladict/tree/dev/src/word-editor"
    click Engines "https://github.com/crimx/ext-saladict/tree/dev/src/app-config"
    click Engines "https://github.com/crimx/ext-saladict/tree/dev/src/components/dictionaries"
    click Macapp "https://github.com/crimx/ext-saladict/tree/dev/mac-app"

    %% Styles
    classDef user fill:#f9e79f,stroke:#000000,stroke-width:2px;
    classDef ui fill:#aed6f1,stroke:#000000,stroke-width:2px;
    classDef background fill:#f5b7b1,stroke:#000000,stroke-width:2px;
    classDef engines fill:#abebc6,stroke:#000000,stroke-width:2px;
    classDef macapp fill:#d7bde2,stroke:#000000,stroke-width:2px;
```
