# dmmdekkd/zhiyu-plugin architecture

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

- Interactive diagram: https://gitdiagram.com/dmmdekkd/zhiyu-plugin
- Repository: https://github.com/dmmdekkd/zhiyu-plugin

## Overview

##### Project Type and Purpose
- This is a Node.js plugin (“zhiyu-plugin”) for the Yunzai-Bot QQ bot framework. It does not stand alone; it extends the Bot at runtime by registering commands, handling events, fetching data from third-party services (Bilibili, Epic Games Store, NetEase Cloud Music, etc.), and persisting state in JSON files.

##### File Structure Analysis
- index.js: Plugin entrypoint. Hooks into Yunzai’s plugin loader.
- apps/: Each sub-folder or .js file implements one feature or command group (b站, epic, 网易云, 文游, 星铁, etc.). Each module exports handlers for message patterns or scheduled tasks.
- components/: Shared libraries (Config.js, Path.js, YamlReader.js). Abstracts file paths and YAML/JSON config loading for all apps.
- utils/: Helpers (e.g., getUin.js) for generic functionality.
- config/: YAML and JS files for plugin configuration and help text. Defines defaults, system themes, and help menus.
- data/: JSON files for runtime persistence (user binds, session data, caches for third-party APIs).
- resources/: Static assets (HTML/CSS for help pages, images for UI, themes).
- scripts/: Build or version-update scripts.
- package.json: Node.js metadata; dependencies and engines (Node 16+).
- README.md: Project overview, feature list, installation, usage, and supported commands.

##### Key Insights from README
- It lists dozens of commands/features, grouped by domain.
- No external database—data persistence is file-based (data/ folder).
- Installs by cloning into Yunzai-Bot’s plugins directory, then restart Bot.
- Configuration is file-based; no dynamic cloud services besides third-party APIs.

a. Main Components
- Yunzai-Bot Core (external component)
- zhiyu-plugin
- Plugin Loader (index.js)
- Feature Modules (apps/)
- Shared Services
– Config Service (components/Config.js + config/)
– File Storage Service (components/Path.js + data/)
– YAML Reader (components/YamlReader.js)
– Utility Library (utils/)
- Static Assets (resources/)
- Scripts (scripts/)
- External Services
- QQ Messaging API (incoming messages, outgoing replies)
- Third-party HTTP APIs (Bilibili, Epic, QQ Open Platform, NetEase Cloud Music, etc.)
b. Relationships & Interactions
- On Bot startup, Yunzai loads index.js → initializes Config Service and registers each apps/* module as a command/event handler.
- Incoming QQ message events flow from Yunzai-Bot Core → Plugin Loader → matching Feature Module.
- Feature Module uses Config Service to read user or global settings.
- Feature Module uses File Storage Service to read/write persistent data.
- Feature Module may call HTTP client (built-in, e.g., axios) to query external APIs.
- Results returned to Yunzai-Bot to send messages back to QQ.
c. Architectural Patterns & Principles
- Modular plugin pattern: each feature is isolated in apps/.
- Shared service singletons: common configuration and path utilities.
- File-based persistence: lightweight, no database.
- Convention-over-configuration: modules auto-discovered under apps/.
d. Technologies & Frameworks
- Node.js (v16+)
- Yaml for configuration (js-yaml via YamlReader)
- JSON for data storage
- HTTP clients (axios or native fetch)
- QQ Open Platform SDK (icqq or Yunzai’s internal abstractions)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Yunzai-Bot Core"
        Core["Yunzai-Bot Core"]:::core
    end

    subgraph "zhiyu-plugin"
        Loader["Plugin Loader\n(index.js)"]:::plugin
        FM["Feature Modules\n(apps/)"]:::plugin

        subgraph "Shared Services"
            ConfigSvc["Config Service\n(components/Config.js + config/)"]:::service
            FileSvc["File Storage Service\n(components/Path.js + data/)"]:::service
            YAMLSvc["YAML Reader Service\n(components/YamlReader.js)"]:::service
            Utils["Utility Library\n(utils/)"]:::service
        end

        Static["Static Assets\n(resources/)"]:::plugin
        Scripts["Build & Version Scripts\n(scripts/)"]:::plugin
        META["package.json"]:::plugin
        Help["README.md"]:::plugin
        Data["Persistent Data Storage\n(data/)"]:::data
    end

    subgraph "External Services"
        APIQQ["QQ Messaging API"]:::external
        HTTP["Third-party HTTP APIs\n(Bilibili, Epic, NetEase, etc.)"]:::external
    end

    Core -->|loads plugin| Loader
    APIQQ -->|message events| Loader
    Loader -->|discovers modules| FM
    Loader -->|initializes| ConfigSvc

    FM -->|uses| ConfigSvc
    FM -->|uses| FileSvc
    FM -->|uses| YAMLSvc
    FM -->|uses| Utils
    FM -->|reads\/writes| Data
    FM -->|serves static assets| Static
    FM -->|executes scripts| Scripts
    FM -->|calls external| HTTP
    FM -->|sends replies| APIQQ

    classDef core fill:#ccc,stroke:#333,color:#000;
    classDef plugin fill:#bbf,stroke:#339,color:#000;
    classDef service fill:#bfb,stroke:#393,color:#000;
    classDef data fill:#f96,stroke:#f60,color:#000;
    classDef external fill:#c9f,stroke:#93c,color:#000;

    click Loader "https://github.com/dmmdekkd/zhiyu-plugin/blob/main/index.js"
    click FM "https://github.com/dmmdekkd/zhiyu-plugin/tree/main/apps/"
    click ConfigSvc "https://github.com/dmmdekkd/zhiyu-plugin/blob/main/components/Config.js"
    click FileSvc "https://github.com/dmmdekkd/zhiyu-plugin/blob/main/components/Path.js"
    click YAMLSvc "https://github.com/dmmdekkd/zhiyu-plugin/blob/main/components/YamlReader.js"
    click Utils "https://github.com/dmmdekkd/zhiyu-plugin/tree/main/utils/"
    click Static "https://github.com/dmmdekkd/zhiyu-plugin/tree/main/resources/"
    click Scripts "https://github.com/dmmdekkd/zhiyu-plugin/tree/main/scripts/"
    click META "https://github.com/dmmdekkd/zhiyu-plugin/blob/main/package.json"
    click Help "https://github.com/dmmdekkd/zhiyu-plugin/blob/main/README.md"
    click Data "https://github.com/dmmdekkd/zhiyu-plugin/tree/main/data/"
```
