# cschiller/zhongwen architecture

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

- Interactive diagram: https://gitdiagram.com/cschiller/zhongwen
- Repository: https://github.com/cschiller/zhongwen

## Overview

##### Project type and purpose
- This is a browser extension (Chrome/Firefox) named “Zhongwen” that provides a pop-up Chinese dictionary and learning tool.
- Key functionality: on-page hover lookups, keyboard navigation, built-in word list, options page, and integration with external learning resources.

##### File structure
Top-level files
- manifest.json – extension configuration and permissions
- background.js / background.html – background (event) page for managing state, context menus, keyboard shortcuts
- content.js – content script injected into web pages for DOM interaction and pop-up rendering
- dict.js – dictionary lookup logic, wrapper around data files
- data/ – raw data: CEDICT files and JSON keyword lists
- css/, js/ – UI assets for options, word list, pop-up styling and behavior
- options.html + js/options.js – configuration UI
- wordlist.html + js/wordlist.js – built-in word list UI and export
- help.html, background.html – auxiliary UI for keyboard shortcut summary
- package.json / .eslintrc.json – build & lint configuration for development

##### Key insights from README
- Architecture is event-driven: content script captures hover & keyboard events; background page handles long-running tasks, storage, and external navigation.
- Data flow involves reading local dictionary files, performing lookups in dict.js, then presenting results.
- Multiple UIs (pop-up, options, word list, help) each in its own HTML/JS subcomponent.

##### Main components
- Browser Extension Shell (manifest)
- Background Component
– Event page (background.js)
– Context menu & keyboard shortcut handlers
– chrome.storage for options & word list persistence
- Content Script Component
– Injected into web pages (content.js + css/content.css)
– Listens for hover & key events
– Sends/receives messages to/from Background
– Renders pop-up UI (background.html or dynamic DOM insertion)
- Data Layer
– dict.js module
– data/cedict idx & u8 files
– grammarKeywordsMin.json, vocabularyKeywordsMin.json
- UI Subsystems
– Pop-up window (hover/keyboard lookup)
– Options page (options.html + js/options.js + css)
– Word list page (wordlist.html + js/wordlist.js + css/wordlist.css)
– Help page (help.html)
- External Services
– Chinese Grammar Wiki
– Skritter, Anki (via export)
– Online dictionaries (via Alt+1..7 shortcuts)

##### Relationships and interactions
1. User hovers or presses key → content script captures event.
2. Content script sends message to background: “lookup word X”.
3. Background or dict.js reads data files, returns lookup result.
5. On “remember” (R) or “export” (C/S) → content script notifies background to update chrome.storage or open export tab.
6. Options page reads/writes settings via chrome.storage.
7. Word list page retrieves stored words, offers export.
8. Context menu and keyboard shortcuts are registered by background, trigger content script or open new tabs for external services.

##### Architectural patterns and design principles
- Event-driven, message-passing within extension boundaries
- Separation of concerns:
- content scripts handle UI injection, user interactions
- background page handles data access, state, and cross-tab actions
- dedicated HTML/JS modules for each UI view
- Data abstraction in dict.js isolating raw data from presentation
- Configurable behavior via options stored in chrome.storage

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Manifest Configuration
    manifest["manifest.json"]:::config

    %% Core Extension Components
    subgraph "Core Extension" 
        direction TB
        background["Background Page"]:::core
        content["Content Script"]:::core
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        dict["dict.js"]:::data
        cedictIdx["cedict.idx"]:::data
        cedictTs["cedict_ts.u8"]:::data
        grammarKW["grammarKeywordsMin.json"]:::data
        vocabKW["vocabularyKeywordsMin.json"]:::data
    end

    %% UI Modules
    subgraph "UI Subsystems"
        direction TB
        popup["Pop-up UI\n(via content script)"]:::ui
        options["Options Page"]:::ui
        wordlist["Word List Page"]:::ui
        help["Help Page"]:::ui
    end

    %% Development & Assets
    subgraph "Development & Build"
        direction TB
        pkg["package.json"]:::config
        eslint[".eslintrc.json"]:::config
        gitignore[".gitignore"]:::config
        pkglock["package-lock.json"]:::config
    end

    subgraph "Assets & Helpers"
        direction TB
        images["images/"]:::assets
        zhuyin["zhuyin.js"]:::assets
        sharedCSS["css/"]:::assets
    end

    %% External Services
    subgraph "External Services"
        direction TB
        grammarWiki["Chinese Grammar Wiki"]:::external
        skritter["Skritter/Anki Export"]:::external
        onlineDicts["Online Dictionaries"]:::external
    end

    %% Connections
    manifest --> core
    core --> dict
    core --> chromeStorage["chrome.storage API"]:::core
    content --> core
    content --> popup
    content -->|"lookupRequest"| core
    core -->|"lookupResponse"| content
    core --> dict
    dict --> cedictIdx
    dict --> cedictTs
    dict --> grammarKW
    dict --> vocabKW
    content --> sharedCSS
    popup --> sharedCSS
    options --> sharedCSS
    wordlist --> sharedCSS
    options -->|"read/write settings"| chromeStorage
    wordlist -->|"retrieve words"| chromeStorage
    content -->|"saveWord/export"| core
    core -->|"open export tab"| skritter
    core -->|"open grammar link"| grammarWiki
    core -->|"open online dict"| onlineDicts

    %% UI Specifics
    options --> optionsHTML["options.html"]:::ui
    options --> optionsJS["js/options.js"]:::ui
    wordlist --> wordlistHTML["wordlist.html"]:::ui
    wordlist --> wordlistJS["js/wordlist.js"]:::ui
    wordlist --> wordlistCSS["css/wordlist.css"]:::ui
    help --> helpHTML["help.html"]:::ui

    %% Click Events for Component Mapping
    click manifest "https://github.com/cschiller/zhongwen/blob/master/manifest.json"
    click background "https://github.com/cschiller/zhongwen/blob/master/background.js"
    click background "https://github.com/cschiller/zhongwen/blob/master/background.html"
    click content "https://github.com/cschiller/zhongwen/blob/master/content.js"
    click sharedCSS "https://github.com/cschiller/zhongwen/blob/master/css/content.css"
    click dict "https://github.com/cschiller/zhongwen/blob/master/dict.js"
    click cedictIdx "https://github.com/cschiller/zhongwen/blob/master/data/cedict.idx"
    click cedictTs "https://github.com/cschiller/zhongwen/blob/master/data/cedict_ts.u8"
    click grammarKW "https://github.com/cschiller/zhongwen/blob/master/data/grammarKeywordsMin.json"
    click vocabKW "https://github.com/cschiller/zhongwen/blob/master/data/vocabularyKeywordsMin.json"
    click optionsHTML "https://github.com/cschiller/zhongwen/blob/master/options.html"
    click optionsJS "https://github.com/cschiller/zhongwen/blob/master/js/options.js"
    click wordlistHTML "https://github.com/cschiller/zhongwen/blob/master/wordlist.html"
    click wordlistJS "https://github.com/cschiller/zhongwen/blob/master/js/wordlist.js"
    click wordlistCSS "https://github.com/cschiller/zhongwen/blob/master/css/wordlist.css"
    click helpHTML "https://github.com/cschiller/zhongwen/blob/master/help.html"
    click pkg "https://github.com/cschiller/zhongwen/blob/master/package.json"
    click eslint "https://github.com/cschiller/zhongwen/blob/master/.eslintrc.json"
    click gitignore "https://github.com/cschiller/zhongwen/blob/master/.gitignore"
    click pkglock "https://github.com/cschiller/zhongwen/blob/master/package-lock.json"
    click images "https://github.com/cschiller/zhongwen/tree/master/images/"
    click zhuyin "https://github.com/cschiller/zhongwen/blob/master/js/zhuyin.js"

    %% Styles
    classDef core fill:#FFD584,stroke:#333,stroke-width:1px
    classDef ui fill:#A3D8F4,stroke:#333,stroke-width:1px
    classDef data fill:#C3F584,stroke:#333,stroke-width:1px
    classDef external fill:#F4A3A3,stroke:#333,stroke-width:1px
    classDef config fill:#D8D8D8,stroke:#333,stroke-width:1px
    classDef assets fill:#E8C3F5,stroke:#333,stroke-width:1px
```
