# nicholass003/topstats architecture

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

- Interactive diagram: https://gitdiagram.com/nicholass003/topstats
- Repository: https://github.com/nicholass003/topstats

## Overview

#### Purpose and Runtime
TopStats is a PHP plugin for PocketMine-MP servers that records player activity metrics and renders ranked in-world leaderboards. PocketMine loads the plugin from `plugin.yml`; the primary lifecycle/bootstrap class is `src/plugin.php`. Runtime configuration and database selection are supplied through `resources/config.yml` and `resources/database.yml`.

#### Plugin Bootstrap and Service Wiring
`src/plugin.php` owns plugin startup/shutdown concerns: loading configuration, initializing persistence, registering listeners/commands, and coordinating leaderboard updates. It is the boundary between PocketMine’s plugin API and internal subsystems. Shared utility behavior resides in `src/utils/util.php`.

#### Statistic Collection Pipeline
PocketMine player/game events are subscribed through `src/listener/events.php`, with event abstractions/handlers in `src/event/event.php` and `src/event/update.php`. These translate server activity into statistic increments or updates rather than coupling event handling directly to storage. Supported metric definitions are centralized in `src/database/data/type.php`; per-player statistic action data is represented by `src/database/data/action.php`.

#### Persistence Abstraction and Providers
`src/database/idatabase.php` defines the database boundary used by the rest of the plugin. Provider implementations support JSON, MySQL, SQLite, and a common SQL layer via `src/database/json.php`, `src/database/mysql.php`, `src/database/sqlite.php`, and `src/database/sql.php`. SQL schemas are packaged at `resources/database/mysql.sql` and `resources/database/sqlite.sql`. Query construction/execution is separated into `src/database/query/query.php` and `src/database/query/action.php`, limiting provider-specific persistence concerns.

#### Leaderboard Lifecycle and Rendering
`src/leaderboard/manager.php` manages created leaderboard instances, lookup, persistence, and refresh orchestration. `src/leaderboard/leaderboard.php` represents an individual displayed ranking, including the README-described player-entity and floating-text models. Rankings consume persisted statistics and are refreshed asynchronously/on schedule through `src/task/update.php`.

#### Commands and Administrative Control
The `/topstats` command entry point is `src/command/topstats.php`. Administrative operations are dispatched to subcommands under `src/command/subcommand/`, notably creation, deletion, listing, teleportation, model/type selection, and autosave. These commands form the operator-facing boundary for managing leaderboard instances rather than directly exposing storage internals.

#### External Integration and Scheduling
`src/external/external.php` and `src/external/types.php` provide a plugin-facing extension boundary for custom statistics from other plugins; `src/external/support/top_voter.php` is a concrete supported integration. Periodic update work is isolated in `src/task/update.php`, preventing ranking/display refresh logic from being embedded in event callbacks. The deployment target is PocketMine-MP; optional infrastructure is local JSON files or configured SQLite/MySQL storage.

Main entry points: [`src/plugin.php`](https://github.com/nicholass003/topstats/blob/stable/src/plugin.php) (Plugin Bootstrap), [`src/database/idatabase.php`](https://github.com/nicholass003/topstats/blob/stable/src/database/idatabase.php) (Database Interface), [`src/leaderboard/manager.php`](https://github.com/nicholass003/topstats/blob/stable/src/leaderboard/manager.php) (Leaderboard Manager), [`src/event/update.php`](https://github.com/nicholass003/topstats/blob/stable/src/event/update.php) (Event Updates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["PocketMine Runtime"]
  node_pocketmine{{"PocketMine-MP<br/>server runtime"}}
  node_bootstrap["Plugin Bootstrap<br/>lifecycle<br/>[plugin.php]"]
  node_config["Plugin Config<br/>configuration<br/>[config.yml]"]
  node_database_config["Database Config<br/>configuration<br/>[database.yml]"]
end

subgraph group_statistics["Statistic Pipeline"]
  node_event_listener["Event Listener<br/>[events.php]"]
  node_event_handlers["Event Updates<br/>event handlers<br/>[update.php]"]
  node_event_model["Event Abstraction<br/>event model<br/>[event.php]"]
  node_metric_types["Metric Types<br/>stat definitions<br/>[type.php]"]
  node_stat_actions["Statistic Actions<br/>action data<br/>[action.php]"]
end

subgraph group_persistence["Persistence"]
  node_database_interface["Database Interface<br/>persistence boundary<br/>[idatabase.php]"]
  node_json_provider[("JSON Provider<br/>database provider<br/>[json.php]")]
  node_mysql_provider[("MySQL Provider<br/>database provider<br/>[mysql.php]")]
  node_sqlite_provider[("SQLite Provider<br/>database provider<br/>[sqlite.php]")]
  node_sql_layer["SQL Layer<br/>shared SQL<br/>[sql.php]"]
  node_query_layer["Query Actions<br/>query layer<br/>[query.php]"]
end

subgraph group_leaderboards["Leaderboards"]
  node_leaderboard_manager["Leaderboard Manager<br/>orchestrator<br/>[manager.php]"]
  node_leaderboard["Leaderboard Display<br/>ranking entity<br/>[leaderboard.php]"]
  node_update_task["Update Task<br/>scheduled task<br/>[update.php]"]
end

subgraph group_administration["Administration &amp; Extensions"]
  node_topstats_command["/topstats Command<br/>command entry<br/>[topstats.php]"]
  node_subcommands["Admin Subcommands<br/>command handlers"]
  node_external_api["External Statistics API<br/>extension boundary<br/>[external.php]"]
  node_top_voter["Top Voter Integration<br/>external adapter<br/>[top_voter.php]"]
end

node_pocketmine -->|"loads lifecycle"| node_bootstrap
node_bootstrap -->|"loads"| node_config
node_bootstrap -->|"selects provider"| node_database_config
node_bootstrap -->|"registers"| node_event_listener
node_bootstrap -->|"registers"| node_topstats_command
node_bootstrap -->|"initializes"| node_database_interface
node_bootstrap -->|"coordinates"| node_leaderboard_manager
node_pocketmine -->|"emits events"| node_event_listener
node_event_listener -->|"dispatches"| node_event_handlers
node_event_handlers -->|"uses"| node_event_model
node_event_handlers -->|"resolves metric"| node_metric_types
node_event_handlers -->|"creates updates"| node_stat_actions
node_stat_actions -->|"persists"| node_database_interface
node_database_interface -.->|"implemented by"| node_json_provider
node_database_interface -.->|"implemented by"| node_mysql_provider
node_database_interface -.->|"implemented by"| node_sqlite_provider
node_mysql_provider -->|"uses"| node_sql_layer
node_sqlite_provider -->|"uses"| node_sql_layer
node_sql_layer -->|"executes through"| node_query_layer
node_leaderboard_manager -->|"loads and saves"| node_database_interface
node_leaderboard_manager -->|"manages"| node_leaderboard
node_update_task -->|"refreshes"| node_leaderboard_manager
node_topstats_command -->|"dispatches"| node_subcommands
node_subcommands -->|"administers"| node_leaderboard_manager
node_external_api -->|"submits custom stats"| node_stat_actions
node_top_voter -->|"integrates via"| node_external_api

click node_bootstrap "https://github.com/nicholass003/topstats/blob/stable/src/plugin.php"
click node_config "https://github.com/nicholass003/topstats/blob/stable/resources/config.yml"
click node_database_config "https://github.com/nicholass003/topstats/blob/stable/resources/database.yml"
click node_event_listener "https://github.com/nicholass003/topstats/blob/stable/src/listener/events.php"
click node_event_handlers "https://github.com/nicholass003/topstats/blob/stable/src/event/update.php"
click node_event_model "https://github.com/nicholass003/topstats/blob/stable/src/event/event.php"
click node_metric_types "https://github.com/nicholass003/topstats/blob/stable/src/database/data/type.php"
click node_stat_actions "https://github.com/nicholass003/topstats/blob/stable/src/database/data/action.php"
click node_database_interface "https://github.com/nicholass003/topstats/blob/stable/src/database/idatabase.php"
click node_json_provider "https://github.com/nicholass003/topstats/blob/stable/src/database/json.php"
click node_mysql_provider "https://github.com/nicholass003/topstats/blob/stable/src/database/mysql.php"
click node_sqlite_provider "https://github.com/nicholass003/topstats/blob/stable/src/database/sqlite.php"
click node_sql_layer "https://github.com/nicholass003/topstats/blob/stable/src/database/sql.php"
click node_query_layer "https://github.com/nicholass003/topstats/blob/stable/src/database/query/query.php"
click node_leaderboard_manager "https://github.com/nicholass003/topstats/blob/stable/src/leaderboard/manager.php"
click node_leaderboard "https://github.com/nicholass003/topstats/blob/stable/src/leaderboard/leaderboard.php"
click node_update_task "https://github.com/nicholass003/topstats/blob/stable/src/task/update.php"
click node_topstats_command "https://github.com/nicholass003/topstats/blob/stable/src/command/topstats.php"
click node_external_api "https://github.com/nicholass003/topstats/blob/stable/src/external/external.php"
click node_top_voter "https://github.com/nicholass003/topstats/blob/stable/src/external/support/top_voter.php"

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_pocketmine,node_bootstrap,node_config,node_database_config toneBlue
class node_event_listener,node_event_handlers,node_event_model,node_metric_types,node_stat_actions toneAmber
class node_database_interface,node_json_provider,node_mysql_provider,node_sqlite_provider,node_sql_layer,node_query_layer toneMint
class node_leaderboard_manager,node_leaderboard,node_update_task toneRose
class node_topstats_command,node_subcommands,node_external_api,node_top_voter toneIndigo
```

## Components

### PocketMine Runtime

- **PocketMine-MP**: server runtime · Hosts the plugin and emits player/game events.
- [Plugin Bootstrap](https://github.com/nicholass003/topstats/blob/stable/src/plugin.php): lifecycle · Wires configuration, services, listeners, commands, and updates. · `src/plugin.php`
- [Plugin Config](https://github.com/nicholass003/topstats/blob/stable/resources/config.yml): configuration · `resources/config.yml`
- [Database Config](https://github.com/nicholass003/topstats/blob/stable/resources/database.yml): configuration · `resources/database.yml`

### Statistic Pipeline

- [Event Listener](https://github.com/nicholass003/topstats/blob/stable/src/listener/events.php): listener · Subscribes to PocketMine activity events. · `src/listener/events.php`
- [Event Updates](https://github.com/nicholass003/topstats/blob/stable/src/event/update.php): event handlers · Converts activity into statistic changes. · `src/event/update.php`
- [Event Abstraction](https://github.com/nicholass003/topstats/blob/stable/src/event/event.php): event model · `src/event/event.php`
- [Metric Types](https://github.com/nicholass003/topstats/blob/stable/src/database/data/type.php): stat definitions · `src/database/data/type.php`
- [Statistic Actions](https://github.com/nicholass003/topstats/blob/stable/src/database/data/action.php): action data · Represents per-player statistic updates. · `src/database/data/action.php`

### Persistence

- [Database Interface](https://github.com/nicholass003/topstats/blob/stable/src/database/idatabase.php): persistence boundary · Provider-independent statistics and leaderboard storage API. · `src/database/idatabase.php`
- [JSON Provider](https://github.com/nicholass003/topstats/blob/stable/src/database/json.php): database provider · `src/database/json.php`
- [MySQL Provider](https://github.com/nicholass003/topstats/blob/stable/src/database/mysql.php): database provider · `src/database/mysql.php`
- [SQLite Provider](https://github.com/nicholass003/topstats/blob/stable/src/database/sqlite.php): database provider · `src/database/sqlite.php`
- [SQL Layer](https://github.com/nicholass003/topstats/blob/stable/src/database/sql.php): shared SQL · Common SQL persistence behavior for SQL providers. · `src/database/sql.php`
- [Query Actions](https://github.com/nicholass003/topstats/blob/stable/src/database/query/query.php): query layer · Builds and executes persistence queries. · `src/database/query/query.php`

### Leaderboards

- [Leaderboard Manager](https://github.com/nicholass003/topstats/blob/stable/src/leaderboard/manager.php): orchestrator · Owns leaderboard instances, persistence, and refresh coordination. · `src/leaderboard/manager.php`
- [Leaderboard Display](https://github.com/nicholass003/topstats/blob/stable/src/leaderboard/leaderboard.php): ranking entity · Renders ranked players as entities or floating text. · `src/leaderboard/leaderboard.php`
- [Update Task](https://github.com/nicholass003/topstats/blob/stable/src/task/update.php): scheduled task · Performs asynchronous or scheduled ranking and display refreshes. · `src/task/update.php`

### Administration & Extensions

- [/topstats Command](https://github.com/nicholass003/topstats/blob/stable/src/command/topstats.php): command entry · `src/command/topstats.php`
- **Admin Subcommands**: command handlers · Creates, deletes, lists, teleports, configures, and saves leaderboards.
- [External Statistics API](https://github.com/nicholass003/topstats/blob/stable/src/external/external.php): extension boundary · Accepts custom statistics from other plugins. · `src/external/external.php`
- [Top Voter Integration](https://github.com/nicholass003/topstats/blob/stable/src/external/support/top_voter.php): external adapter · `src/external/support/top_voter.php`

## Connections

- PocketMine-MP → Plugin Bootstrap: loads lifecycle
- Plugin Bootstrap → Plugin Config: loads
- Plugin Bootstrap → Database Config: selects provider
- Plugin Bootstrap → Event Listener: registers
- Plugin Bootstrap → /topstats Command: registers
- Plugin Bootstrap → Database Interface: initializes
- Plugin Bootstrap → Leaderboard Manager: coordinates
- PocketMine-MP → Event Listener: emits events
- Event Listener → Event Updates: dispatches
- Event Updates → Event Abstraction: uses
- Event Updates → Metric Types: resolves metric
- Event Updates → Statistic Actions: creates updates
- Statistic Actions → Database Interface: persists
- Database Interface → JSON Provider: implemented by
- Database Interface → MySQL Provider: implemented by
- Database Interface → SQLite Provider: implemented by
- MySQL Provider → SQL Layer: uses
- SQLite Provider → SQL Layer: uses
- SQL Layer → Query Actions: executes through
- Leaderboard Manager → Database Interface: loads and saves
- Leaderboard Manager → Leaderboard Display: manages
- Update Task → Leaderboard Manager: refreshes
- /topstats Command → Admin Subcommands: dispatches
- Admin Subcommands → Leaderboard Manager: administers
- External Statistics API → Statistic Actions: submits custom stats
- Top Voter Integration → External Statistics API: integrates via