# festivaldev/webstone architecture

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

## Overview

##### Main Components
- Mod Loader / Minecraft Environment:
– Represent the overall Minecraft client/server environment where the Forge mod is installed.
– Show Forge as the mod loader that integrates this mod into Minecraft.
- Webstone Core Module:
– This includes the main package “tf.festival.webstone” and its subcomponents.
– Components include block and entity registration (WebstoneBlocks, WebstoneBlockEntities, WebstoneItems, and the Registry class), configuration (WebstoneConfig), and command handling (WebstoneCommand).
- WebSocket Server:
– Represent the dedicated WebSocket server module (classes like WebstoneSocketServer and WebstoneSocketServerMessages) which listens on port 4321.
– This component manages connections to external WebSocket clients (e.g., a remote web UI).
- Data & Business Logic:
– Include the data model layer represented by classes in the “data” package (WebstoneBlock, WebstoneBlockGroup) and the “block” and “blockentity” packages (WebstoneRemoteBlock and WebstoneRemoteBlockEntity).
– This layer handles game-specific logic and the state representation of remote controllable blocks.
- External Client/Web UI:
– Represent remote control clients (like the one hosted at http://webstone.festival.tf or the one available in the GitHub webui repo) which connect via WebSocket.
- Configuration and Security:
– Include the configuration file structure (described in README and located in a specific mod configuration folder) and the security options (passphrase and TLS configuration) that influence how the WebSocket server accepts connections.

##### Relationships and Data Flows
– The WebSocket Server to External Clients, indicating two-way communication and broadcast of state changes.
– The Webstone Core Module to the WebSocket Server (e.g., via WebstoneSocketServer) to show that events from the mod (such as block toggles) are sent over the network.
– The Mod Loader (Forge) to the Webstone components, indicating that Forge initializes and manages registration and events.
– The configuration module (WebstoneConfig) feeding parameters (passphrase, port, security options) into the WebSocket Server.
– The Data & Business Logic layer interacting with both the mod’s in-game events and the external WebSocket communication (i.e., block update notifications).

##### Architectural Patterns & Design Principles
- The design follows a layered approach where Minecraft integration, networking, and game logic are separated.
- Notice the event-driven communication between the WebSocket Server and connected clients (broadcast updates when a block’s state changes).
- Secure communication is optionally enforced via TLS and passphrase authentication.
- The project uses a modular structure to ease registration of blocks and commands within Minecraft’s Forge modding framework.

##### Relevant Technologies and Frameworks
- Java and the Forge Mod Loader for Minecraft.
- Gradle as the build system (indicated by build.gradle, settings.gradle, gradle wrapper files).
- WebSockets for network communication (using core Java networking libraries or custom WebSocket implementations).
- JSON as a data exchange format for API calls between server and clients.
- Configuration via TOML file (as specified for Webstone).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Minecraft Environment
    subgraph "Minecraft Environment"
        Forge("Forge Mod Loader"):::mod
        modsToml("Mod Configuration File"):::config
    end

    %% Webstone Mod Components
    subgraph "Webstone Mod"
        Core("Core Module (Registration/Commands)"):::core
        Config("Configuration (WebstoneConfig)"):::config
        WS("WebSocket Server"):::net
    end

    %% Data & Business Logic Layer
    subgraph "Data & Business Logic"
        DataModel("Data Model (WebstoneBlock & WebstoneBlockGroup)"):::data
        BlockLogic("Block Logic (WebstoneRemoteBlock)"):::data
        BlockEntityLogic("Block Entity Logic (WebstoneRemoteBlockEntity)"):::data
    end

    %% External Client / Web UI
    External("External Client/Web UI"):::client

    %% Relationships and Data Flow
    Forge -->|"Initializes"| Core
    modsToml -->|"ConfigInjection"| Config
    Config -->|"SetParameters"| WS
    Core -->|"SendsEvents"| WS
    WS -->|"Broadcast:BlockUpdate"| External
    External -->|"ClientRequest"| WS
    Core ---|"UsesLogic"| DataModel
    DataModel ---|"Interacts"| BlockLogic
    DataModel ---|"Interacts"| BlockEntityLogic

    %% Click Events
    click modsToml "https://github.com/festivaldev/webstone/blob/forge-1.20.1/src/main/resources/META-INF/mods.toml"
    click Core "https://github.com/festivaldev/webstone/tree/forge-1.20.1/src/main/java/tf/festival/webstone"
    click WS "https://github.com/festivaldev/webstone/blob/forge-1.20.1/src/main/java/tf/festival/webstone/WebstoneSocketServer.java"
    click WS "https://github.com/festivaldev/webstone/blob/forge-1.20.1/src/main/java/tf/festival/webstone/WebstoneSocketServerMessages.java"
    click Config "https://github.com/festivaldev/webstone/blob/forge-1.20.1/src/main/java/tf/festival/webstone/WebstoneConfig.java"
    click DataModel "https://github.com/festivaldev/webstone/tree/forge-1.20.1/src/main/java/tf/festival/webstone/data"
    click BlockLogic "https://github.com/festivaldev/webstone/tree/forge-1.20.1/src/main/java/tf/festival/webstone/block"
    click BlockEntityLogic "https://github.com/festivaldev/webstone/tree/forge-1.20.1/src/main/java/tf/festival/webstone/blockentity"

    %% Styles
    classDef mod fill:#f2d7d5,stroke:#e74c3c,stroke-width:2px;
    classDef core fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef net fill:#d6eaf8,stroke:#2980b9,stroke-width:2px;
    classDef data fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef client fill:#fdebd0,stroke:#e67e22,stroke-width:2px;
    classDef config fill:#ebdef0,stroke:#8e44ad,stroke-width:2px;
```
