# hdb-studio/qshopwebui architecture

> Architecture diagram of the GitHub repository hdb-studio/qshopwebui, 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/hdb-studio/qshopwebui
- Repository: https://github.com/hdb-studio/qshopwebui

## Overview

QshopWebUI is a Minecraft shop browsing and administration panel. A browser user searches and filters shops, views item and shop details, and receives results through the frontend API client and Express server, which queries PostgreSQL. Admins additionally manage shop data, accounts, settings, announcements, and backups. The README documents polling and webhook synchronization with QSFilterPlugin. The sampled code is partial, so feature coverage follows the README where implementation details were not available; arrows are limited to documented or sampled interactions.

Main entry points: [`server.js`](https://github.com/hdb-studio/qshopwebui/blob/main/server.js) (Express API), [`js/app.js`](https://github.com/hdb-studio/qshopwebui/blob/main/js/app.js) (Shop UI), [`index.html`](https://github.com/hdb-studio/qshopwebui/blob/main/index.html) (Web interface), [`js/db.js`](https://github.com/hdb-studio/qshopwebui/blob/main/js/db.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser experience"]
  node_page["Web interface<br/>[index.html]"]
  node_app["Shop UI<br/>[app.js]"]
  node_api_client["API client<br/>[db.js]"]
end

subgraph group_service["Shop service"]
  node_server["Express API<br/>[server.js]"]
  node_shop_queries["Shop discovery<br/>[server.js]"]
  node_shop_management["Shop management<br/>[server.js]"]
  node_stats_activity["Stats and activity<br/>[server.js]"]
end

subgraph group_data["Persistent data"]
  node_postgres[("PostgreSQL")]
  node_backup_files[("Backup files")]
end

subgraph group_admin["Administration"]
  node_auth["Admin authentication<br/>[server.js]"]
  node_settings["Configuration<br/>[server.js]"]
  node_announcements["Announcements<br/>[server.js]"]
  node_backups["Backup and restore<br/>[server.js]"]
end

subgraph group_sync["Plugin sync"]
  node_qsfilter["QSFilterPlugin"]
  node_sync_status["Plugin sync status<br/>[server.js]"]
end

node_shopper(("Browser user"))
node_admin_user(("Administrator"))

node_shopper -->|"opens"| node_page
node_page -->|"loads"| node_app
node_app -->|"requests data"| node_api_client
node_api_client -->|"calls REST API"| node_server
node_server -->|"dispatches queries"| node_shop_queries
node_shop_queries -->|"reads shops"| node_postgres
node_server -->|"dispatches changes"| node_shop_management
node_shop_management -->|"writes shop data"| node_postgres
node_server -->|"dispatches stats"| node_stats_activity
node_stats_activity -->|"reads and records"| node_postgres
node_admin_user -->|"uses admin panel"| node_page
node_app -->|"requests login"| node_auth
node_auth -->|"stores sessions"| node_postgres
node_app -->|"edits configuration"| node_settings
node_settings -->|"updates environment"| node_server
node_app -->|"manages notices"| node_announcements
node_announcements -->|"stores notices"| node_postgres
node_app -->|"requests backup actions"| node_backups
node_backups -->|"backs up and restores"| node_postgres
node_backups -->|"writes and reads"| node_backup_files
node_server -->|"maintains sync"| node_sync_status
node_sync_status -.->|"polls and syncs"| node_qsfilter
node_qsfilter -.->|"sends webhooks"| node_server

click node_page "https://github.com/hdb-studio/qshopwebui/blob/main/index.html"
click node_app "https://github.com/hdb-studio/qshopwebui/blob/main/js/app.js"
click node_api_client "https://github.com/hdb-studio/qshopwebui/blob/main/js/db.js"
click node_server "https://github.com/hdb-studio/qshopwebui/blob/main/server.js"
click node_shop_queries "https://github.com/hdb-studio/qshopwebui/blob/main/server.js"
click node_shop_management "https://github.com/hdb-studio/qshopwebui/blob/main/server.js"
click node_stats_activity "https://github.com/hdb-studio/qshopwebui/blob/main/server.js"
click node_auth "https://github.com/hdb-studio/qshopwebui/blob/main/server.js"
click node_settings "https://github.com/hdb-studio/qshopwebui/blob/main/server.js"
click node_announcements "https://github.com/hdb-studio/qshopwebui/blob/main/server.js"
click node_backups "https://github.com/hdb-studio/qshopwebui/blob/main/server.js"
click node_sync_status "https://github.com/hdb-studio/qshopwebui/blob/main/server.js"

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_page,node_app,node_api_client,node_shopper toneBlue
class node_server,node_shop_queries,node_shop_management,node_stats_activity toneAmber
class node_postgres,node_backup_files toneMint
class node_auth,node_settings,node_announcements,node_backups toneRose
class node_qsfilter,node_sync_status,node_admin_user toneIndigo
```

## Components

### Browser experience

- [Web interface](https://github.com/hdb-studio/qshopwebui/blob/main/index.html): `index.html`
- [Shop UI](https://github.com/hdb-studio/qshopwebui/blob/main/js/app.js): `js/app.js`
- [API client](https://github.com/hdb-studio/qshopwebui/blob/main/js/db.js): `js/db.js`

### Shop service

- [Express API](https://github.com/hdb-studio/qshopwebui/blob/main/server.js): `server.js`
- [Shop discovery](https://github.com/hdb-studio/qshopwebui/blob/main/server.js): `server.js`
- [Shop management](https://github.com/hdb-studio/qshopwebui/blob/main/server.js): `server.js`
- [Stats and activity](https://github.com/hdb-studio/qshopwebui/blob/main/server.js): `server.js`

### Persistent data

- **PostgreSQL**
- **Backup files**

### Administration

- [Admin authentication](https://github.com/hdb-studio/qshopwebui/blob/main/server.js): `server.js`
- [Configuration](https://github.com/hdb-studio/qshopwebui/blob/main/server.js): `server.js`
- [Announcements](https://github.com/hdb-studio/qshopwebui/blob/main/server.js): `server.js`
- [Backup and restore](https://github.com/hdb-studio/qshopwebui/blob/main/server.js): `server.js`

### Plugin sync

- **QSFilterPlugin**
- [Plugin sync status](https://github.com/hdb-studio/qshopwebui/blob/main/server.js): `server.js`

### Other components

- **Browser user**
- **Administrator**

## Connections

- Browser user → Web interface: opens
- Web interface → Shop UI: loads
- Shop UI → API client: requests data
- API client → Express API: calls REST API
- Express API → Shop discovery: dispatches queries
- Shop discovery → PostgreSQL: reads shops
- Express API → Shop management: dispatches changes
- Shop management → PostgreSQL: writes shop data
- Express API → Stats and activity: dispatches stats
- Stats and activity → PostgreSQL: reads and records
- Administrator → Web interface: uses admin panel
- Shop UI → Admin authentication: requests login
- Admin authentication → PostgreSQL: stores sessions
- Shop UI → Configuration: edits configuration
- Configuration → Express API: updates environment
- Shop UI → Announcements: manages notices
- Announcements → PostgreSQL: stores notices
- Shop UI → Backup and restore: requests backup actions
- Backup and restore → PostgreSQL: backs up and restores
- Backup and restore → Backup files: writes and reads
- Express API → Plugin sync status: maintains sync
- Plugin sync status → QSFilterPlugin: polls and syncs
- QSFilterPlugin → Express API: sends webhooks