# earthjasonlin/zzz-signal-search-export architecture

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

- Interactive diagram: https://gitdiagram.com/earthjasonlin/zzz-signal-search-export
- Repository: https://github.com/earthjasonlin/zzz-signal-search-export

## Overview

##### Project type and purpose
- This is an Electron-based desktop application (built with electron-vite) that extracts “gacha” (调频) history records from a game.
- The main purpose is to read the user’s authKey (either by parsing the local game log or by running an HTTP MITM proxy), then call the game’s gacha-history API, aggregate the results, and finally export or display them in a Vue-based UI (with charts and Excel exports).

##### File structure
- Top‐level build/config:
- `.electron-vite/`: custom build scripts and config for electron-vite.
- `package.json`, `vite.config.js`, `postcss.config.js`, `tailwind.config.js`.
- `src/main/`: Node “main process” code:
- `main.js`: boots Electron, creates windows, sets up IPC.
- `bridge.js`: defines secure IPC channels.
- `getData.js`, `UIGFJson.js`, `excel.js`: core business logic for fetching data, formatting to UIGF, writing to Excel.
- `module/`: pluggable submodules—`extract-zip` (log parsing), `node-mitmproxy` (proxy server), `system-proxy`.
- `update/`: auto-update logic.
- `i18n.js`: loads translations from `src/i18n/*.json`.
- `src/renderer/`: Vue single-page application (“renderer process”):
- `App.vue` + components (GachaDetail, PieChart, Setting).
- `gachaDetail.js`, `utils.js`: client-side helpers.
- `index.html`, `index.css`, `main.js`: entry point and styles.
- Data/config files in `src/`: `gachaType.json`, `idJson.json`, language packs.
- `tools/`: standalone Python helper script.

##### Key insights from README
- The app reads authKey via two strategies (log-parsing or MITM proxy).
- UI actions (“Load Data”, “Add Account”) send IPC requests to the main process.
- Results can be previewed in the UI and exported to files.
- Supports multi-language via JSON in `src/i18n/`.
- Auto-updater built-in.

a. Main components:
- Renderer Process (Vue UI)
- Main Process (Node/Electron)
- Extraction Modules (log parser, proxy server)
- Data Fetcher (calls game API)
- Data Formatter/Exporter (UIGF JSON, Excel)
- Auto-Updater
- Local File System (for logs, caches, exported files)
- External Services (Game API endpoints)
b. Relationships & interactions:
1. User clicks “Load Data” in Renderer → sends IPC to Main.
2. Main invokes Extraction Module (either log parser or starts MITM proxy + system-proxy).
3. Extraction Module returns authKey → Main passes it to Data Fetcher.
4. Data Fetcher calls External Game API over HTTPS → retrieves gacha records.
5. Main hands raw data to Data Formatter → writes to UIGF JSON and/or Excel on File System.
6. Main notifies Renderer via IPC → Renderer loads & visualizes data (PieChart, GachaDetail).
7. On “Export” in UI → IPC to Main → Main writes final file.
8. Auto-Updater periodically checks version via `update/index.js`.
c. Architectural patterns/design principles:
- Electron’s multi-process model: clear separation of UI (renderer) vs business logic & OS access (main).
- Modular extraction strategy (plugin-like modules under `main/module/`).
- IPC bridge to enforce security and typed messages.
- MVVM in Vue for the front end.
- Single source of truth for i18n.
d. Key technologies/frameworks/libraries:
- Electron + electron-vite + Vite
- Vue 3 (SFCs), Tailwind CSS
- node-mitmproxy, exceljs (or similar)
- JSON-based config and language packs
- auto-updater library (electronic-update script)
- IPC via `contextBridge` in `bridge.js`

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Renderer Process
    subgraph "Renderer Process (Vue UI)"
        direction TB
        UIEntry["UI Entry Point\n(main.js)"]:::renderer
        UIRoot["UI Root Component\n(App.vue)"]:::renderer
        GachaDetail["Gacha Detail View\n(GachaDetail.vue)"]:::renderer
        PieChart["Pie Chart View\n(PieChart.vue)"]:::renderer
        Setting["Settings View\n(Setting.vue)"]:::renderer
        RendererHelper1["gachaDetail helper\n(gachaDetail.js)"]:::renderer
        RendererHelper2["General utils\n(utils.js)"]:::renderer
        StaticHTML["HTML Template\n(index.html)"]:::renderer
        StaticCSS["CSS Styles\n(index.css)"]:::renderer
    end

    %% Main Process
    subgraph "Main Process (Node)"
        direction TB
        IPCBridge["IPC Bridge\n(bridge.js)"]:::main
        subgraph "Extraction Modules"
            direction TB
            LogParser["Log Parser\n(extract-zip.js)"]:::module
            MITMProxy["MITM Proxy Server\n(node-mitmproxy.js)"]:::module
            SysProxy["System Proxy Toggler\n(system-proxy.js)"]:::module
        end
        DataFetcher["Data Fetcher\n(getData.js)"]:::module
        Formatter["UIGF JSON Formatter\n(UIGFJson.js)"]:::module
        Exporter["Excel Exporter\n(excel.js)"]:::module
        Updater["Auto-Updater\n(update/index.js)"]:::module
        I18nLoader["i18n Loader\n(i18n.js)"]:::module
        UtilsGeneral["General utils\n(utils.js)"]:::module
        UtilsMerge["Data Merge Utility\n(utils/mergeData.js)"]:::module
        ConfigFile["App Config\n(config.js)"]:::module
        GachaType["Gacha Types\n(gachaType.json)"]:::module
        IDMap["ID Mappings\n(idJson.json)"]:::module
    end

    %% External Services
    GameAPI["External Game API"]:::external
    FileSystem["Local File System"]:::storage

    %% Interactions
    UIRoot -->|"Load Data / Export"| IPCBridge
    IPCBridge -->|request authKey| LogParser
    IPCBridge -->|or start proxy| MITMProxy
    IPCBridge -->|toggle proxy| SysProxy
    LogParser -->|return authKey| IPCBridge
    MITMProxy -->|return authKey| IPCBridge
    IPCBridge -->|pass authKey| DataFetcher
    DataFetcher -->|HTTPS API call| GameAPI
    GameAPI -->|gacha records| DataFetcher
    DataFetcher -->|raw data| Formatter
    Formatter -->|UIGF JSON| FileSystem
    Formatter -->|formatted data| IPCBridge
    IPCBridge -->|notify data ready| UIRoot
    UIRoot -->|"Export Excel"| IPCBridge
    IPCBridge -->|generate file| Exporter
    Exporter -->|xlsx file| FileSystem
    Updater -->|check updates| GameAPI
    Updater -->|download/update| FileSystem

    %% Click Events
    click UIEntry "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/renderer/main.js"
    click UIRoot "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/renderer/App.vue"
    click GachaDetail "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/renderer/components/GachaDetail.vue"
    click PieChart "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/renderer/components/PieChart.vue"
    click Setting "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/renderer/components/Setting.vue"
    click RendererHelper1 "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/renderer/gachaDetail.js"
    click RendererHelper2 "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/renderer/utils.js"
    click StaticHTML "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/renderer/index.html"
    click StaticCSS "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/renderer/index.css"
    click IPCBridge "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/main/bridge.js"
    click DataFetcher "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/main/getData.js"
    click Formatter "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/main/UIGFJson.js"
    click Exporter "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/main/excel.js"
    click LogParser "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/main/module/extract-zip.js"
    click MITMProxy "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/main/module/node-mitmproxy.js"
    click SysProxy "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/main/module/system-proxy.js"
    click Updater "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/main/update/index.js"
    click I18nLoader "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/main/i18n.js"
    click UtilsGeneral "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/main/utils.js"
    click UtilsMerge "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/main/utils/mergeData.js"
    click ConfigFile "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/main/config.js"
    click GachaType "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/gachaType.json"
    click IDMap "https://github.com/earthjasonlin/zzz-signal-search-export/blob/main/src/idJson.json"

    %% Styling
    classDef renderer fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef main fill:#E8F0D0,stroke:#6F42C1,color:#6F42C1;
    classDef module fill:#DFF8E0,stroke:#28A745,color:#28A745;
    classDef external fill:#FFE8D0,stroke:#D73A49,color:#D73A49;
    classDef storage fill:#FFF5E1,stroke:#E36209,color:#E36209;
```
