# topper-mc/chattopper architecture

> Architecture diagram of the GitHub repository topper-mc/chattopper, 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/topper-mc/chattopper
- Repository: https://github.com/topper-mc/chattopper

## Overview

##### Primary Components
- Main Plugin Class: At the center is ChatTopper.java—the entry point of the plugin that initializes and registers all other components during the plugin’s startup.
- Command Handling: The GetWordTopCommand.java class deals with the “/getwordtop” command. This is important since it provides user interaction to fetch the leaderboard items.
- Chat Listening: ChatListener.java listens to chat messages (through the Bukkit event system) and relays data to be processed.
- Word Holders & Update Agents: WordHolder.java (and its related update agent in the agent sub-package) maintain the current count/state of words.
- Managers: There are several manager classes:
- HolderManager.java: Likely oversees the lifecycle and state of word data.
- StorageManager.java: Might deal with saving/loading persisted data.
- WordQueryManager.java and WordQueryForward.java: Likely responsible for handling queries against the stored data to produce ordered leaderboard results.
- Placeholder Integration: PlaceholderHook.java registers and handles placeholders (e.g., %chattopper_top_key;<index>%), allowing external systems or other plugin components to access leaderboard details.

b. Components & Their Roles:
- Plugin Bootstrap: ChatTopper.java
- Event Listener: ChatListener.java (connected to the main plugin to receive chat events)
- Command Interface: GetWordTopCommand.java (receives user commands, typically via Bukkit’s command registration)
- Data Holders & Agents: WordHolder.java and UpdateAgent.java (handle in-memory word tracking and periodic updates)
- Managers:
- HolderManager.java (coordinates the overall word tracking)
- StorageManager.java (handles persistence, suggesting data storage flow)
- WordQueryManager.java & WordQueryForward.java (process leaderboard retrieval from word data)
- Integration Hooks: PlaceholderHook.java (exposes data externally via placeholders)
c. Relationships & Data Flow:
- The ChatListener is triggered by Minecraft chat events; it passes word data or events to the HolderManager.
- The HolderManager updates the WordHolder and might delegate to the UpdateAgent for periodic updates.
- When a player enters the command (/getwordtop), the GetWordTopCommand accesses the WordQueryManager (and/or WordQueryForward) to retrieve and format leaderboard data.
- The PlaceholderHook subscribes to external calls for placeholder data, calling into WordQueryManager or the stored data to return the word or count.
- StorageManager is connected edge-wise with managers to perform any load or save operations as needed.
d. Architectural & Design Patterns:
- Event Driven: ChatListener reacting to in-game events.
- Modularization: Separation of concerns between handling commands, managing state, and offering external hooks.
- Dependency Injection (possibly through the plugin framework): Components are likely registered via the main plugin class.
- Use of Managers for centralized coordination.
e. Technologies & Frameworks:
- Bukkit/Spigot API (implicit because of the plugin structure and plugin.yml file)
- Maven (as indicated by the pom.xml)

##### Final Reminders
- All components should be clearly labeled along with brief notes on their role.
- Similarly purposed components to make the architectural flow intuitive.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Plugin
    CT["ChatTopper (Plugin Bootstrap)"]:::core
    
    %% Command Handling Branch
    GWT["GetWordTopCommand (/getwordtop command)"]:::command
    WQM["WordQueryManager (Processes leaderboard retrieval)"]:::manager
    WQF["WordQueryForward (Query Forwarding)"]:::manager

    %% Event Handling Branch
    CL["ChatListener (Listens to chat events)"]:::event
    HM["HolderManager (Coordinates word tracking)"]:::manager
    WH["WordHolder (Maintains word count)"]:::data
    UA["UpdateAgent (Periodic update agent)"]:::data

    %% Integration Branch
    PH["PlaceholderHook (Exposes placeholders)"]:::integration

    %% Storage Component
    SM["StorageManager (Persistence Manager)"]:::storage

    %% Connections from the Core Plugin
    CT -->|"RegistersEvents"| CL
    CT -->|"RegistersCommand"| GWT

    %% Event Handling Flow
    CL -->|"UpdatesWordCounts"| HM
    HM -->|"ManagesData"| WH
    HM -->|"TriggersUpdates"| UA

    %% Command Handling Flow
    GWT -->|"FetchesLeaderboard"| WQM
    WQM -->|"ForwardsQuery"| WQF

    %% Integration Flow
    PH -->|"ResolvesData"| WQM

    %% Storage Connections
    HM -->|"Saves/LoadsData"| SM
    WQM -->|"Saves/LoadsData"| SM

    %% Click Events
    click CT "https://github.com/topper-mc/chattopper/blob/master/src/main/java/me/hsgamer/chattopper/ChatTopper.java"
    click GWT "https://github.com/topper-mc/chattopper/blob/master/src/main/java/me/hsgamer/chattopper/command/GetWordTopCommand.java"
    click CL "https://github.com/topper-mc/chattopper/blob/master/src/main/java/me/hsgamer/chattopper/listener/ChatListener.java"
    click WH "https://github.com/topper-mc/chattopper/blob/master/src/main/java/me/hsgamer/chattopper/holder/WordHolder.java"
    click UA "https://github.com/topper-mc/chattopper/blob/master/src/main/java/me/hsgamer/chattopper/holder/agent/UpdateAgent.java"
    click HM "https://github.com/topper-mc/chattopper/blob/master/src/main/java/me/hsgamer/chattopper/manager/HolderManager.java"
    click SM "https://github.com/topper-mc/chattopper/blob/master/src/main/java/me/hsgamer/chattopper/manager/StorageManager.java"
    click WQM "https://github.com/topper-mc/chattopper/blob/master/src/main/java/me/hsgamer/chattopper/manager/WordQueryManager.java"
    click WQF "https://github.com/topper-mc/chattopper/blob/master/src/main/java/me/hsgamer/chattopper/manager/WordQueryForward.java"
    click PH "https://github.com/topper-mc/chattopper/blob/master/src/main/java/me/hsgamer/chattopper/hook/PlaceholderHook.java"

    %% Styles
    classDef core fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef event fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef command fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef manager fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef integration fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef storage fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef data fill:#FFFACD,stroke:#333,stroke-width:2px;
```
