# hiram-wong/zyplayer architecture

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

- Interactive diagram: https://gitdiagram.com/hiram-wong/zyplayer
- Repository: https://github.com/hiram-wong/zyplayer

## Overview

##### Project type & purpose
- ZyPlayer is a full‐stack desktop application built with Electron (Node.js main process + Chromium renderer), Vue 3 + TDesign in the frontend, and an embedded HTTP/IPC‐based backend. It bundles local database migrations, service modules, a mini‐Express‐style API server, Python “proxy” scripts, filesystem access, auto‐updater, tray/menu/shortcut managers, and a Vue-powered SPA UI.

##### Top‐level components
A. Electron Main Process (Node.js)
- Core modules:
– db (common, schema, migration, service layers)
– server (routes/v1/* REST endpoints for analyze, drive, file, history, lab, live, parse, player, plugin, proxy, setting, site, star, system)
– ipc (custom channels exposed via contextBridge)
– protocol (custom URL schemes)
– menu, tray, shortcut, winManager, update, logger
- Resources & scripts (resources/t3PyBase Python proxy & spider)
- Filesystem: config, user data, plugin, database directories
- Auto-Updater: GitHub Actions + electron‐builder orchestration

B. Preload Script
- Exposes safe IPC and Node APIs to renderer via contextBridge

C. Renderer Process (Chromium)
- Vue 3 SPA (src/renderer):
– Components & pages (media player cores, code‐editor, layouts)
– Vue Router for navigation (router/modules)
– Pinia store for state management (store/modules, plugins)
– API layer (api/*.ts) calling embedded backend via fetch
– Assets, locales (i18n), styles, sketches for design (desgin/*.sketch)

D. External Services
- Video platforms embedded via iframe or sniffer (iqiyi, qq, sohu, etc.)
- IPTV streams (m3u playlists, EPG)
- CMS adapters (nodejs, drpy, json, xml)
- Alist drives, WebDAV backup

##### Interactions & data flow
- Renderer → Preload (IPC invoke/listen) → Main modules (protocol, menu, window control, native dialogs)
- Renderer → HTTP API → Main/server/routes/v1/* → service layer → db → SQLite (on disk)
- Main → spawn Python proxy (resources/t3PyBase) → scrape external sites → return data via server endpoints
- Main → network calls (fetch) for CMS, IPTV, external APIs
- Main → file operations (fs) for plugins, config, local files

##### Architectural patterns & design principles
- Layered backend: Controller (server/routes) → Service (core/db/service) → Data Access (common/curd, schema)
- Separation of concerns: UI vs. business logic vs. persistence vs. native OS integration
- MVVM in the renderer (Vue components + Pinia stores)
- Modular plugin/adapter architecture for CMS & player cores
- IPC vs. HTTP boundary: use contextBridge for native vs. full REST API for data operations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Process
    subgraph "Electron Main Process" 
        direction TB
        MainEntry["Entry Point\nsrc/main/index.ts"]:::backend
        MainDBCore["DB Modules\n(common, schema, migration, service)"]:::backend
        MainServer["Server\nREST controllers & routes"]:::backend
        subgraph "Server: v1 Routes"
            direction TB
            RouteCMSAdapter["CMS Adapters"]:::backend
            RouteIPTV["IPTV Streams Endpoint"]:::backend
        end
        MainIPC["IPC Channels"]:::backend
        MainProtocol["Custom Protocols"]:::backend
        MainMenu["Menu Manager"]:::backend
        MainTray["Tray Manager"]:::backend
        MainShortcut["Shortcut Manager"]:::backend
        MainWinManager["Window Manager"]:::backend
        MainUpdate["Auto-Updater"]:::backend
        MainLogger["Logger"]:::backend
    end

    %% Preload Script
    subgraph "Preload Script"
        direction TB
        Preload["ContextBridge Exposure"]:::backend
    end

    %% Renderer Process
    subgraph "Renderer Process" 
        direction TB
        RendererRoot["Vue SPA Root"]:::frontend
        RendererComponents["UI Components"]:::frontend
        RendererPages["Pages"]:::frontend
        RendererRouter["Router Modules"]:::frontend
        RendererStore["State Management"]:::frontend
        RendererAPI["API Layer"]:::frontend
        RendererAssets["Assets"]:::frontend
        RendererLocales["Locales"]:::frontend
        RendererStyles["Styles & Themes"]:::frontend
    end

    %% Local OS Resources
    subgraph "Local OS Resources"
        direction TB
        SQLite["SQLite Database"]:::datastore
        FileSystem["Filesystem\n(config, plugin, user files)"]:::filesystem
        PythonProxy["Python Proxy & Spider"]:::filesystem
    end

    %% External Services
    subgraph "External Services"
        direction TB
        VideoPlatforms["Video Platforms"]:::external
        IPTV["IPTV Streams"]:::external
        CMS["CMS Endpoints"]:::external
        Alist["Alist / WebDAV"]:::external
        GitHub["GitHub Updates"]:::external
    end

    %% Interactions
    RendererRoot -->|HTTP/REST| MainServer
    RendererAPI -->|HTTP/REST| MainServer
    RendererRoot -->|IPC| Preload
    Preload -->|IPC| MainIPC
    MainIPC -->|invoke protocol| MainProtocol
    MainIPC -->|window control| MainWinManager
    MainIPC -->|menu/tray| MainMenu
    MainServer -->|Data Access| MainDBCore
    MainDBCore -->|reads/writes| SQLite
    MainServer -->|spawn/child_process| PythonProxy
    MainServer -->|network calls| CMS
    MainServer -->|network calls| IPTV
    MainServer -->|network calls| Alist
    MainUpdate -->|check updates| GitHub
    MainServer -->|fs operations| FileSystem

    %% Click Events
    click MainEntry "https://github.com/hiram-wong/zyplayer/blob/main/src/main/index.ts"
    click MainDBCore "https://github.com/hiram-wong/zyplayer/tree/main/src/main/core/db"
    click MainServer "https://github.com/hiram-wong/zyplayer/tree/main/src/main/core/server"
    click RouteCMSAdapter "https://github.com/hiram-wong/zyplayer/tree/main/src/main/core/server/routes/v1/site/cms/adapter"
    click RouteIPTV "https://github.com/hiram-wong/zyplayer/blob/main/src/main/core/server/routes/v1/live/iptv.ts"
    click MainIPC "https://github.com/hiram-wong/zyplayer/blob/main/src/main/core/ipc/index.ts"
    click MainProtocol "https://github.com/hiram-wong/zyplayer/blob/main/src/main/core/protocol/index.ts"
    click MainMenu "https://github.com/hiram-wong/zyplayer/blob/main/src/main/core/menu/index.ts"
    click MainTray "https://github.com/hiram-wong/zyplayer/blob/main/src/main/core/tray/index.ts"
    click MainShortcut "https://github.com/hiram-wong/zyplayer/blob/main/src/main/core/shortcut/index.ts"
    click MainWinManager "https://github.com/hiram-wong/zyplayer/blob/main/src/main/core/winManger/index.ts"
    click MainUpdate "https://github.com/hiram-wong/zyplayer/blob/main/src/main/core/update/index.ts"
    click MainLogger "https://github.com/hiram-wong/zyplayer/blob/main/src/main/core/logger/index.ts"
    click PythonProxy "https://github.com/hiram-wong/zyplayer/tree/main/resources/t3PyBase"
    click Preload "https://github.com/hiram-wong/zyplayer/blob/main/src/preload/index.ts"
    click RendererRoot "https://github.com/hiram-wong/zyplayer/blob/main/src/renderer/src/main.ts"
    click RendererComponents "https://github.com/hiram-wong/zyplayer/tree/main/src/renderer/src/components"
    click RendererPages "https://github.com/hiram-wong/zyplayer/tree/main/src/renderer/src/pages"
    click RendererRouter "https://github.com/hiram-wong/zyplayer/tree/main/src/renderer/src/router/modules"
    click RendererStore "https://github.com/hiram-wong/zyplayer/tree/main/src/renderer/src/store"
    click RendererAPI "https://github.com/hiram-wong/zyplayer/tree/main/src/renderer/src/api"
    click RendererAssets "https://github.com/hiram-wong/zyplayer/tree/main/src/renderer/src/assets"
    click RendererLocales "https://github.com/hiram-wong/zyplayer/tree/main/src/renderer/src/locales"
    click RendererStyles "https://github.com/hiram-wong/zyplayer/tree/main/src/renderer/src/style"

    %% Styles
    classDef frontend fill:#B3D4FC,stroke:#0366D6,color:#0366D6;
    classDef backend fill:#D4F8D4,stroke:#28A745,color:#28A745;
    classDef datastore fill:#E0E0E0,stroke:#666666,color:#333333;
    classDef filesystem fill:#FFD8A8,stroke:#FF8C00,color:#8B4513;
    classDef external fill:#FFF4C1,stroke:#D4A017,color:#A67C00;
```
