# sangtacviet/stv-manga-translator architecture

> Architecture diagram of the GitHub repository sangtacviet/stv-manga-translator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sangtacviet/stv-manga-translator
- Repository: https://github.com/sangtacviet/stv-manga-translator

## Overview

##### Project Type and Purpose
- This is a front-end–only Tampermonkey userscript named “stv-manga-translator.”
- Purpose: when you browse supported manga/manhua/manhwa websites, it automatically detects text elements on the page and replaces them with translated text.

##### File Structure Analysis
- Top level:
- package.json & build.js → Node-based build pipeline (bundles/minifies)
- README.md → high-level description
- src/
- base_userscript.js → userscript metadata block (@name, @match, @require, etc.) and core injection logic
- header.js → common constants (metadata, site‐matching patterns)
- class.js → core classes/interfaces (Plugin interface, translation engine wrapper, DOM utilities)
- plugins/ → one folder per supported site (e.g., comic_naver_com.js implements site‐specific selectors, parsing rules, translation injection)

##### README Insights
- Confirms it’s a browser userscript for automated manga translation.

##### Core Components
a. Runtime Components
1. Tampermonkey Container (Browser Extension)
2. Injected Userscript (final bundled script)
3. Core Orchestrator (code from base_userscript.js + class.js)
4. Plugin Modules (each file under src/plugins)
5. Browser DOM & CSS Selectors (target pages)
6. External Translation Service API (e.g., Google Translate)
b. Build‐Time Components
1. Node.js Build Script (build.js)
2. package.json & devDependencies (e.g., bundler, minifier)

##### Relationships and Data Flow
- Build Phase:
- build.js reads src/*.js → applies bundler/minifier → outputs final userscript
- package.json drives npm scripts
- Runtime Phase:
1. Tampermonkey injects the bundled script when URL matches header.js patterns.
2. Userscript’s Core Orchestrator initializes.
3. Core loads the matching Plugin Module based on current host.
4. Plugin scans page DOM for text elements (panels, speech bubbles).
5. Extracted text is sent via Fetch/XHR to the external translation API.
6. API response (translated text) is returned.
7. Plugin replaces original text nodes in the DOM with translations.

##### Architectural Patterns and Principles
- Plugin Architecture: each site is decoupled as a separate module implementing a shared interface.
- Single Responsibility:
- Header handles metadata/matching.
- Core classes handle orchestration and API calls.
- Plugins handle site‐specific selectors and DOM mutation.
- Build Pipeline Separation: clear split between development (Node.js) and runtime (browser).

##### Technology & Libraries
- JavaScript (ES6 modules)
- Node.js (build tooling)
- Tampermonkey (userscript loader)
- Fetch API or XMLHttpRequest (for translation service)

##### Detailing Level
- Header.js feeding the Core with site-matching rules.
- For each plugin (e.g., comic_naver_com), note its domain pattern and DOM selectors.
- HTTP request/response cycle with external API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Phase
    subgraph "Build Phase"
        direction TB
        pkg["package.json"]:::build
        build["build.js"]:::build
        bundler["Bundler & Minifier"]:::build
        pkg -->|"npm scripts"| build
        build -->|"bundles & minifies"| bundler
        bundler -->|"outputs"| userscript["Bundled Userscript"]:::runtime
    end

    %% Runtime Phase
    subgraph "Runtime Phase"
        direction TB
        tm["Tampermonkey Container"]:::runtime
        userscript -->|"injects on match"| tm
        tm -->|"loads script"| header["header.js<br/>(Site-Matching Rules)"]:::runtime
        tm -->|"loads script"| orchestrator["Core Orchestrator<br/>(base_userscript.js)"]:::runtime
        orchestrator -->|"uses interface"| classes["Core Classes & Interfaces<br/>(class.js)"]:::runtime
        classes -->|"defines"| te["TranslationEngine"]:::runtime
        classes -->|"defines"| pi["PluginInterface"]:::runtime
        orchestrator -->|"selects plugin"| plugin["comic_naver_com.js"]:::plugin
        plugin -->|"scans DOM"| dom["Browser DOM & CSS Selectors"]:::runtime
        dom -->|"extract text"| plugin
        plugin -->|"fetches translation"| api["External Translation Service API"]:::external
        api -->|"returns translation"| plugin
        plugin -->|"replaces DOM text"| dom
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        readme["README.md"]:::docs
    end

    %% Click Events
    click orchestrator "https://github.com/sangtacviet/stv-manga-translator/blob/main/src/base_userscript.js"
    click classes "https://github.com/sangtacviet/stv-manga-translator/blob/main/src/class.js"
    click header "https://github.com/sangtacviet/stv-manga-translator/blob/main/src/header.js"
    click plugin "https://github.com/sangtacviet/stv-manga-translator/blob/main/src/plugins/comic_naver_com.js"
    click build "https://github.com/sangtacviet/stv-manga-translator/blob/main/build.js"
    click pkg "https://github.com/sangtacviet/stv-manga-translator/blob/main/package.json"
    click readme "https://github.com/sangtacviet/stv-manga-translator/blob/main/README.md"

    %% Styles
    classDef build fill:#f9f,stroke:#333,stroke-width:1px
    classDef runtime fill:#bbf,stroke:#333,stroke-width:1px
    classDef plugin fill:#fbf,stroke:#333,stroke-width:1px
    classDef external fill:#bfb,stroke:#333,stroke-width:1px
    classDef docs fill:#ffe,stroke:#333,stroke-width:1px
```
