# pikapikagfy/qsfilterplugin architecture

> Architecture diagram of the GitHub repository pikapikagfy/qsfilterplugin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pikapikagfy/qsfilterplugin
- Repository: https://github.com/pikapikagfy/qsfilterplugin

## Overview

QS Filter is a Paper/QuickShop-Hikari plugin that periodically collects shop listings, compares selling prices with weighted historical transaction prices, and exposes filtered listings and price data through HTTP and in-game commands. Transaction events provide historical records; shop-change events can be forwarded to a configured webhook. The graph reflects the supplied source excerpts and tree; several API routes and plugin wiring are only partially sampled, so uncertain calls are omitted.

Main entry points: [`src/main/java/cn/hdbstudio/qsfilter/QSFilterPlugin.java`](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/QSFilterPlugin.java) (Plugin Lifecycle), [`src/main/java/cn/hdbstudio/qsfilter/api/ApiHttpServer.java`](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/api/ApiHttpServer.java) (HTTP API), [`src/main/java/cn/hdbstudio/qsfilter/storage/TransactionRepository.java`](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/storage/TransactionRepository.java) (Transaction Repository), [`src/main/java/cn/hdbstudio/qsfilter/filter/PriceFilterEngine.java`](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/filter/PriceFilterEngine.java) (Price Filter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Plugin Runtime"]
  node_plugin["Plugin Lifecycle"]
  node_config["Plugin Config<br/>[PluginConfig.java]"]
  node_encryption["API Encryption"]
end

subgraph group_shops["Shop Processing"]
  node_bridge["QuickShop Bridge"]
  node_collector["Shop Collector"]
  node_filter["Price Filter"]
  node_shopdata["Shop Records<br/>[FilteredShop.java]"]
end

subgraph group_history["Transaction History"]
  node_txlistener["Transaction Listener"]
  node_repository["Transaction Repository"]
  node_database[("SQLite History")]
end

subgraph group_interfaces["Interfaces"]
  node_api["HTTP API<br/>[ApiHttpServer.java]"]
  node_commands["Plugin Commands"]
  node_webhook["Shop Change Webhook"]
end

node_players(("Players/Admins"))
node_httpclients(("HTTP Clients"))
node_quickshop["QuickShop-Hikari"]
node_webhookreceiver(("Webhook Receiver"))

node_players -->|"invoke commands"| node_commands
node_httpclients -->|"request endpoints"| node_api
node_quickshop -->|"provide shop data"| node_bridge
node_plugin -->|"load settings"| node_config
node_plugin -->|"initialize"| node_encryption
node_plugin -->|"initialize"| node_repository
node_plugin -->|"start collection"| node_collector
node_plugin -->|"start server"| node_api
node_plugin -->|"register listener"| node_txlistener
node_plugin -->|"register listener"| node_webhook
node_collector -->|"fetch shops"| node_bridge
node_collector -->|"process listings"| node_filter
node_bridge -->|"convert listings"| node_shopdata
node_filter -->|"read weighted prices"| node_repository
node_filter -->|"annotate and cache"| node_shopdata
node_txlistener -->|"record transactions"| node_repository
node_repository -->|"query and write"| node_database
node_api -->|"read shops and stats"| node_filter
node_api -->|"encrypt responses"| node_encryption
node_api -->|"query price data"| node_repository
node_commands -->|"request price endpoint"| node_api
node_webhook -.->|"post shop changes"| node_webhookreceiver

click node_plugin "https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/QSFilterPlugin.java"
click node_config "https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/config/PluginConfig.java"
click node_encryption "https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/crypto/EncryptionUtil.java"
click node_bridge "https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/quickshop/QuickShopBridge.java"
click node_collector "https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/quickshop/ShopDataCollector.java"
click node_filter "https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/filter/PriceFilterEngine.java"
click node_shopdata "https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/filter/FilteredShop.java"
click node_txlistener "https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/quickshop/TransactionListener.java"
click node_repository "https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/storage/TransactionRepository.java"
click node_database "https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/storage/DatabaseManager.java"
click node_api "https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/api/ApiHttpServer.java"
click node_commands "https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/QSFilterPlugin.java"
click node_webhook "https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/webhook/ShopChangeWebhook.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin,node_config,node_encryption,node_httpclients toneBlue
class node_bridge,node_collector,node_filter,node_shopdata toneAmber
class node_txlistener,node_repository,node_database,node_webhookreceiver toneMint
class node_api,node_commands,node_webhook toneRose
class node_players,node_quickshop toneIndigo
```

## Components

### Plugin Runtime

- [Plugin Lifecycle](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/QSFilterPlugin.java): `src/main/java/cn/hdbstudio/qsfilter/QSFilterPlugin.java`
- [Plugin Config](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/config/PluginConfig.java): `src/main/java/cn/hdbstudio/qsfilter/config/PluginConfig.java`
- [API Encryption](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/crypto/EncryptionUtil.java): `src/main/java/cn/hdbstudio/qsfilter/crypto/EncryptionUtil.java`

### Shop Processing

- [QuickShop Bridge](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/quickshop/QuickShopBridge.java): `src/main/java/cn/hdbstudio/qsfilter/quickshop/QuickShopBridge.java`
- [Shop Collector](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/quickshop/ShopDataCollector.java): `src/main/java/cn/hdbstudio/qsfilter/quickshop/ShopDataCollector.java`
- [Price Filter](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/filter/PriceFilterEngine.java): `src/main/java/cn/hdbstudio/qsfilter/filter/PriceFilterEngine.java`
- [Shop Records](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/filter/FilteredShop.java): `src/main/java/cn/hdbstudio/qsfilter/filter/FilteredShop.java`

### Transaction History

- [Transaction Listener](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/quickshop/TransactionListener.java): `src/main/java/cn/hdbstudio/qsfilter/quickshop/TransactionListener.java`
- [Transaction Repository](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/storage/TransactionRepository.java): `src/main/java/cn/hdbstudio/qsfilter/storage/TransactionRepository.java`
- [SQLite History](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/storage/DatabaseManager.java): `src/main/java/cn/hdbstudio/qsfilter/storage/DatabaseManager.java`

### Interfaces

- [HTTP API](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/api/ApiHttpServer.java): `src/main/java/cn/hdbstudio/qsfilter/api/ApiHttpServer.java`
- [Plugin Commands](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/QSFilterPlugin.java): `src/main/java/cn/hdbstudio/qsfilter/QSFilterPlugin.java`
- [Shop Change Webhook](https://github.com/pikapikagfy/qsfilterplugin/blob/master/src/main/java/cn/hdbstudio/qsfilter/webhook/ShopChangeWebhook.java): `src/main/java/cn/hdbstudio/qsfilter/webhook/ShopChangeWebhook.java`

### Other components

- **Players/Admins**
- **HTTP Clients**
- **QuickShop-Hikari**
- **Webhook Receiver**

## Connections

- Players/Admins → Plugin Commands: invoke commands
- HTTP Clients → HTTP API: request endpoints
- QuickShop-Hikari → QuickShop Bridge: provide shop data
- Plugin Lifecycle → Plugin Config: load settings
- Plugin Lifecycle → API Encryption: initialize
- Plugin Lifecycle → Transaction Repository: initialize
- Plugin Lifecycle → Shop Collector: start collection
- Plugin Lifecycle → HTTP API: start server
- Plugin Lifecycle → Transaction Listener: register listener
- Plugin Lifecycle → Shop Change Webhook: register listener
- Shop Collector → QuickShop Bridge: fetch shops
- Shop Collector → Price Filter: process listings
- QuickShop Bridge → Shop Records: convert listings
- Price Filter → Transaction Repository: read weighted prices
- Price Filter → Shop Records: annotate and cache
- Transaction Listener → Transaction Repository: record transactions
- Transaction Repository → SQLite History: query and write
- HTTP API → Price Filter: read shops and stats
- HTTP API → API Encryption: encrypt responses
- HTTP API → Transaction Repository: query price data
- Plugin Commands → HTTP API: request price endpoint
- Shop Change Webhook → Webhook Receiver: post shop changes