# viv2king/ms-node architecture

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

- Interactive diagram: https://gitdiagram.com/viv2king/ms-node
- Repository: https://github.com/viv2king/ms-node

## Overview

##### Project Type and Purpose
- This is a Bukkit/Spigot Minecraft plugin written in Java (Gradle‐based) that manages user interactions, commands, event listeners, and a simple in‐memory “agent” subsystem.
- Its core is the `Node` enum (the plugin lifecycle manager), which registers commands and listeners at startup and unregisters them on shutdown.

##### File Structure Analysis
Top‐level:
- build.gradle, gradle wrapper, settings.gradle → Gradle build system
- README.md → project overview
- src/main/java/mc/node/… → all Java source organized into subpackages
- src/main/resources/plugin.yml → Bukkit plugin descriptor

Key subpackages under `mc.node`:
- node/ → `NodePlugin` (the JavaPlugin subclass) and `Node` enum lifecycle
- node/agent/ → `Agent` model, `AgentManager`, repository interfaces
- node/bukkit/commands → command classes (e.g. `ExampleCommand`)
- node/bukkit/listeners → event listeners (e.g. `UserListener`, `BlockListener`)
- node/objects/… → helper builders and reflection utilities
- plugin.yml → metadata, commands definitions

##### README Insights
- Describes plugin lifecycle (`Node.INSTANCE.start(...)` and `.stop()`), features (agent management, example command, graceful shutdown).
- Mentions use of Bukkit API, Lombok, and the `Registry` utility for wiring commands/listeners.

##### Main Components
a. External System:
- Bukkit/Spigot Server (plugin loader & event bus)
b. Plugin Core:
- NodePlugin (extends `JavaPlugin`)
- Node enum (lifecycle orchestrator)
c. Subsystems:
- Agent Subsystem
– AgentManager
– AgentRepository (interface)
– Agent entities
- Command Subsystem
– ExampleCommand (implements Bukkit’s `CommandExecutor`)
– Registry (registerCommand)
- Event Listener Subsystem
– UserListener, BlockListener (implement Bukkit event handlers)
– Registry (registerListener)
- Utility Modules
– Reflection utils (`Reflections`, `FieldAccessor`)
– Chat & Screen builders (action bar, titles, legacy support)

##### Relationships & Data Flows
- On plugin enable: Bukkit → invokes NodePlugin#onEnable → calls `Node.INSTANCE.start(plugin)`
- Node → uses Registry to register commands & listeners with server’s command map and event bus
- User actions in game → Bukkit EventBus → UserListener → interacts with AgentManager → possibly reads/writes via AgentRepository
- Commands (e.g. `/example`) → dispatched by Bukkit → ExampleCommand.execute → may call AgentManager or utility builders
- On plugin disable: Node.INSTANCE.stop() → HandlerList.unregisterAll(plugin)

##### Architectural Patterns & Principles
- Plugin (Inversion of Control) via Bukkit API
- Registry pattern for decoupled registration of listeners/commands
- Command pattern for encapsulating in-game commands
- Event‐driven architecture leveraging Bukkit’s event bus
- Repository abstraction for agent storage

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External System
    Server["Bukkit/Spigot Server\nPlugin Loader & EventBus"]:::external

    %% Plugin Core
    subgraph "Plugin Core"
        NodePlugin["NodePlugin (JavaPlugin)"]:::core
        NodeEnum["Node (lifecycle enum)"]:::core
    end

    %% Agent Subsystem
    subgraph "Agent Subsystem"
        AgentManager["AgentManager"]:::subsystem
        AgentRepo["AgentRepository (interface)"]:::subsystem
        RepositoryIface["Repository (interface)"]:::subsystem
        AgentEntity["Agent (model)"]:::subsystem
    end

    %% Command Subsystem
    subgraph "Command Subsystem"
        ExampleCmd["ExampleCommand"]:::subsystem
    end

    %% Event Listener Subsystem
    subgraph "Event Listener Subsystem"
        UserListener["UserListener"]:::subsystem
        BlockListener["BlockListener"]:::subsystem
    end

    %% Utility Modules
    subgraph "Utility Modules"
        RegistryUtil["Registry"]:::util
        Reflections["Reflections"]:::util
        FieldAccessor["FieldAccessor"]:::util
        MsgBuilder["MessageBuilder"]:::util
        LegacyMsg["LegacyMessageBuilder"]:::util
        ActionBar["ActionBarBuilder"]:::util
        LegacyActionBar["LegacyActionBarBuilder"]:::util
        TitleBar["TitleBuilder"]:::util
        LegacyTitle["LegacyTitleBuilder"]:::util
    end

    %% Configuration
    PluginYML["plugin.yml\n(metadata)"]:::core

    %% Relationships
    Server -->|"onEnable"| NodePlugin
    NodePlugin -->|"calls start() on"| NodeEnum
    NodeEnum -->|"uses"| RegistryUtil
    RegistryUtil -->|"registers commands & listeners with"| Server

    Server -->|"dispatches command to"| ExampleCmd
    ExampleCmd -->|"may call"| AgentManager
    ExampleCmd -->|"may call utilities"| MsgBuilder

    Server -->|"dispatches event to"| UserListener
    Server -->|"dispatches event to"| BlockListener
    UserListener -->|"interacts with"| AgentManager
    BlockListener -->|"interacts with"| AgentManager

    AgentManager -->|"uses"| AgentRepo
    AgentRepo -->|"manages"| AgentEntity
    AgentRepo -->|"extends"| RepositoryIface

    NodePlugin -->|"reads metadata from"| PluginYML

    NodeEnum -->|"onDisable calls stop()"| Server

    %% Click Events
    click NodePlugin "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/NodePlugin.java"
    click NodeEnum "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/Node.java"
    click AgentEntity "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/agent/Agent.java"
    click AgentManager "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/agent/AgentManager.java"
    click AgentRepo "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/agent/repository/AgentRepository.java"
    click RepositoryIface "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/agent/repository/Repository.java"
    click ExampleCmd "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/bukkit/commands/ExampleCommand.java"
    click RegistryUtil "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/objects/plugin/registry/Registry.java"
    click UserListener "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/bukkit/listeners/UserListener.java"
    click BlockListener "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/bukkit/listeners/BlockListener.java"
    click Reflections "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/objects/plugin/reflection/Reflections.java"
    click FieldAccessor "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/objects/plugin/reflection/FieldAccessor.java"
    click MsgBuilder "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/objects/chat/MessageBuilder.java"
    click LegacyMsg "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/objects/chat/LegacyMessageBuilder.java"
    click ActionBar "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/objects/screen/actionbar/ActionBarBuilder.java"
    click LegacyActionBar "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/objects/screen/actionbar/LegacyActionBarBuilder.java"
    click TitleBar "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/objects/screen/title/TitleBuilder.java"
    click LegacyTitle "https://github.com/viv2king/ms-node/blob/master/src/main/java/mc/node/objects/screen/title/LegacyTitleBuilder.java"
    click PluginYML "https://github.com/viv2king/ms-node/blob/master/src/main/resources/plugin.yml"

    %% Styles
    classDef core fill:#a0d2eb,stroke:#333,stroke-width:1px
    classDef subsystem fill:#b7e4c7,stroke:#333,stroke-width:1px
    classDef util fill:#ffe066,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
```
