# heyimblake/hiveranks architecture

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

- Interactive diagram: https://gitdiagram.com/heyimblake/hiveranks
- Repository: https://github.com/heyimblake/hiveranks

## Overview

##### Main Components
- Plugin Core: At the heart, you have the main plugin class (HiveRanks.java) which acts as the entry point. This component interfaces with the Bukkit/Spigot API to load the plugin and register events/commands.
- Command Handling: The project organizes its command handling into a series of sub-packages:
- Base Command (HiveRanksCommand.java, HiveRanksSubCommandExecutor.java)
- Subcommands (GetSubCommand.java, MyRankSubCommand.java, ResetSubCommand.java, SetSubCommand.java)
- A subcommand handler (HiveRanksSubCommandHandler.java) and annotations for subcommands, indicating a structured way to parse arguments and delegate command tasks.
- Event Listeners: The listeners package (with PlayerJoinListener.java) handles in-game events such as player login, triggering rank updates or cache refreshes.
- Task Scheduling: The runnables package contains an UpdateCacheRunnable.java that manages periodic cache updating, ensuring that player rank information remains up-to-date.
- Utility Components: Under the util package, you have classes for handling detailed functionalities:
- CachedPlayer.java (likely representing cached player data)
- HiveRank.java (possibly an enumeration or model for rank definitions)
- MessageUtils.java for formatting or sending messages, and ServerSound.java to manage audio cues.
- Caching and Resource Files: Resources like cache.json and plugin.yml in the src/main/resources directory are used for plugin configuration and caching state.
- External Dependencies: Notice references to Maven (pom.xml), Travis CI configuration for continuous integration, and bStats for server statistics tracking.

##### Relationships and Interactions
- Command Flow: User commands (triggered by players or admin actions) are picked up by the HiveRanksCommand, dispatched to the subcommand executor and handler. Subcommands are organized logically (set, get, reset, myrank) to perform various operations.
- Event Flow: The PlayerJoinListener captures player join events. This triggers actions like checking or updating HiveMC rank data, maybe refreshing the cached data.
- Scheduling Tasks: UpdateCacheRunnable is scheduled (likely via Bukkit’s scheduler) to periodically refresh the rank cache, ensuring that user rank information remains current even without active command invocation.
- Utility Interactions: Various util classes are used throughout the logical flow for data management (CachedPlayer) and formatting outputs (MessageUtils), ensuring that the user experience is consistent.
- Configuration/External Communication: The plugin.yml integrates the plugin into the Bukkit/Spigot ecosystem by defining commands, permissions, and metadata. bStats is integrated to send periodic anonymous usage data.

##### Architectural Patterns and Principles
- Modularity: The project’s structure (commands, listeners, runnables, and utils) reflects a separation of concerns. Each package and class handles distinct aspects of the plugin’s functionality.
- Event-driven Design: The plugin depends on Bukkit’s event system. Listeners (e.g., for player join) react to game events, triggering corresponding business logic.
- Command Pattern: By separating the main command from its subcommands and handlers, the plugin effectively uses the command design pattern, facilitating easier extension and maintenance.
- Asynchronous Scheduling: The use of runnables for cache updates hints at asynchronous or scheduled task management, which is typical in game plugins to prevent blocking the main game thread.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Inputs
    PI["Player Input"]:::external
    GE["Game Event"]:::external

    %% Plugin Core
    subgraph "Plugin Core"
        HR["HiveRanks"]:::core
    end

    %% Command Handling
    subgraph "Command Handling"
        HRC["HiveRanksCommand"]:::command
        HRSC["HiveRanksSubCommandExecutor"]:::command
        HRSH["HiveRanksSubCommandHandler"]:::command
        GSC["GetSubCommand"]:::subcommand
        MRSC["MyRankSubCommand"]:::subcommand
        RSC["ResetSubCommand"]:::subcommand
        SSC["SetSubCommand"]:::subcommand
    end

    %% Event Listeners
    subgraph "Event Listeners"
        PJL["PlayerJoinListener"]:::event
    end

    %% Task Scheduling
    subgraph "Task Scheduling"
        UCR["UpdateCacheRunnable"]:::task
    end

    %% Utilities
    subgraph "Utilities"
        CP["CachedPlayer"]:::util
        HRU["HiveRank"]:::util
        MU["MessageUtils"]:::util
        SS["ServerSound"]:::util
    end

    %% Configuration and Resources
    subgraph "Configuration"
        CACHE["cache.json"]:::config
        PLUGINY["plugin.yml"]:::config
    end

    %% External Dependencies
    BSP["Bukkit/Spigot API"]:::external
    BST["bStats"]:::external
    MAV["Maven (pom.xml)"]:::external
    TC["Travis CI"]:::external

    %% Relationships
    %% External triggers
    PI -->|"triggers"| HRC
    GE -->|"triggers"| PJL

    %% Core registration
    HR -->|"registers"| HRC
    HR -->|"registers"| PJL
    HR -->|"schedules"| UCR
    HR -->|"utilizes"| MU
    HR -->|"utilizes"| SS
    HR -->|"reads"| PLUGINY
    HR -->|"updates"| CACHE
    HR -->|"calls"| BSP
    HR -->|"reports"| BST
    HR -->|"built with"| MAV
    HR -->|"monitored by"| TC

    %% Command Flow
    HRC -->|"executes"| HRSC
    HRSC -->|"handles"| HRSH
    HRSH -->|"dispatches"| GSC
    HRSH -->|"dispatches"| MRSC
    HRSH -->|"dispatches"| RSC
    HRSH -->|"dispatches"| SSC

    %% Task Scheduling interactions
    UCR -->|"updates"| CP
    UCR -->|"updates"| HRU

    %% Click Events
    click HR "https://github.com/heyimblake/hiveranks/blob/master/src/main/java/me/heyimblake/hiveranks/HiveRanks.java"
    click HRC "https://github.com/heyimblake/hiveranks/blob/master/src/main/java/me/heyimblake/hiveranks/commands/HiveRanksCommand.java"
    click HRSC "https://github.com/heyimblake/hiveranks/blob/master/src/main/java/me/heyimblake/hiveranks/commands/HiveRanksSubCommandExecutor.java"
    click HRSH "https://github.com/heyimblake/hiveranks/blob/master/src/main/java/me/heyimblake/hiveranks/commands/HiveRanksSubCommandHandler.java"
    click GSC "https://github.com/heyimblake/hiveranks/blob/master/src/main/java/me/heyimblake/hiveranks/commands/subcommands/GetSubCommand.java"
    click MRSC "https://github.com/heyimblake/hiveranks/blob/master/src/main/java/me/heyimblake/hiveranks/commands/subcommands/MyRankSubCommand.java"
    click RSC "https://github.com/heyimblake/hiveranks/blob/master/src/main/java/me/heyimblake/hiveranks/commands/subcommands/ResetSubCommand.java"
    click SSC "https://github.com/heyimblake/hiveranks/blob/master/src/main/java/me/heyimblake/hiveranks/commands/subcommands/SetSubCommand.java"
    click PJL "https://github.com/heyimblake/hiveranks/blob/master/src/main/java/me/heyimblake/hiveranks/listeners/PlayerJoinListener.java"
    click UCR "https://github.com/heyimblake/hiveranks/blob/master/src/main/java/me/heyimblake/hiveranks/runnables/UpdateCacheRunnable.java"
    click CP "https://github.com/heyimblake/hiveranks/blob/master/src/main/java/me/heyimblake/hiveranks/util/CachedPlayer.java"
    click HRU "https://github.com/heyimblake/hiveranks/blob/master/src/main/java/me/heyimblake/hiveranks/util/HiveRank.java"
    click MU "https://github.com/heyimblake/hiveranks/blob/master/src/main/java/me/heyimblake/hiveranks/util/MessageUtils.java"
    click SS "https://github.com/heyimblake/hiveranks/blob/master/src/main/java/me/heyimblake/hiveranks/util/ServerSound.java"
    click CACHE "https://github.com/heyimblake/hiveranks/blob/master/src/main/resources/cache.json"
    click PLUGINY "https://github.com/heyimblake/hiveranks/blob/master/src/main/resources/plugin.yml"

    %% Styles
    classDef core fill:#ffd1dc,stroke:#333,stroke-width:2px;
    classDef command fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef subcommand fill:#99ddff,stroke:#333,stroke-width:2px;
    classDef event fill:#ffe6cc,stroke:#333,stroke-width:2px;
    classDef task fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef util fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef config fill:#d1ecf1,stroke:#333,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:2px;
```
