# winds-studio/leaf architecture

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

- Interactive diagram: https://gitdiagram.com/winds-studio/leaf
- Repository: https://github.com/winds-studio/leaf

## Overview

##### Project Type and Purpose
- This is an open-source, performance-oriented fork of the Minecraft Paper server (“Leaf”), built on top of Gale and incorporating patches from multiple other forks.
- It consists of two main deliverables:
- leaf-api – a compile-only API module that exposes hooks, events, annotations, and configuration abstractions for plugin authors
- leaf-server – the actual patched server implementation (Paperclip JAR) that runs under the Bukkit/Spigot/Paper plugin loader

##### File Structure
- Top-level build: Gradle wrapper, build.gradle.kts, settings.gradle.kts, scripts for releasing and upstream commits, and a `build-data` directory for import/version tracking.
- leaf-api: patch files plus a Maven/Gradle-published API artifact.
- leaf-server: paper/gale/minecraft patches, src/main/java with subpackages:
- org.dreeam.leaf (bootstrapping, async subsystem, commands, config modules)
- gg.pufferfish (Sentry integration, utility executors)
- net.caffeinemc (Lithium mod integration)
- org.leavesmc.leaves (protocol handlers: custom payloads, Jade, Syncmatica, replay, bot)
- others for Purpur commands, Linear region format, Matter hashing
- Configuration and build scripts tie all of these together via Paperweight’s “applyAllPatches” and “createMojmapPaperclipJar” tasks.

##### README for Additional Insights
- Purpose: high-performance fork, async pathfinding/mob spawning/entity tracking, broad plugin compatibility, mod-protocol support (Jade, Syncmatica, AppleSkin, etc.), Sentry error reporting, bStats metrics.
- Build instructions and license details.

##### Detail Balance
- Every major package and subsystem without overcrowding: use nested containers or layering.
- Fork/patch workflow and the runtime interactions between platform, Leaf code, and external services.
- Keep the focus on how the project is structured for both build-time (patch application) and runtime (async, config, protocol).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Platform["Bukkit/Spigot/Paper Loader"]:::external
    VanillaServer["Vanilla Minecraft Server"]:::external
    SentryService["Sentry"]:::external
    bStatsService["bStats"]:::external

    %% Build System
    subgraph "Build System"
        direction TB
        GradleWrapper["Gradle Wrapper"]:::build
        BuildGradle["build.gradle.kts"]:::build
        SettingsGradle["settings.gradle.kts"]:::build
        GradleScripts["scripts"]:::build
        PaperweightTasks["Paperweight Tasks"]:::build
    end

    %% API Module
    subgraph "leaf-api" 
        direction TB
        leafApi["leaf-api"]:::api
        leafApiBuildPatch["build.gradle.kts.patch"]:::api
        leafApiPatches["paper-patches/features"]:::api
    end

    %% Server Module
    subgraph "leaf-server"
        direction TB

        subgraph "Patch Pipeline"
            direction TB
            galePatches["gale-patches/features"]:::build
            mcPatches["minecraft-patches/features"]:::build
            paperPatches["paper-patches/features"]:::build
        end

        LeafBootstrap["LeafBootstrap"]:::impl

        subgraph "Async Subsystem"
            direction TB
            AsyncLocator["AsyncLocator"]:::async
            AsyncPath["AsyncPath & Processor"]:::async
            MultithreadedTracker["MultithreadedTracker"]:::async
            PWTEventScheduler["PWTEventScheduler"]:::async
        end

        subgraph "Configuration Modules"
            direction TB
            ConfigCore["org.dreeam.leaf.config"]:::impl
            ConfigModules["config/modules"]:::impl
        end

        subgraph "Command Framework"
            direction TB
            LeafCommand["LeafCommand"]:::impl
            MSPTCommand["MSPTCommand"]:::impl
            ReloadCommand["ReloadCommand"]:::impl
            VersionCommand["VersionCommand"]:::impl
        end

        subgraph "Sentry Integration"
            direction TB
            PufferfishSentryAppender["PufferfishSentryAppender"]:::impl
            SentryManager["SentryManager"]:::impl
        end

        subgraph "Mod Integrations"
            direction TB
            Lithium["Lithium Mod"]:::impl
            PurpurAFK["AFKCommand"]:::impl
        end

        subgraph "Protocol Layers"
            direction TB
            LeavesProtocolCore["LeavesProtocol & Manager"]:::protocol
            JadeProtocol["Jade Protocol"]:::protocol
            SyncmaticaProtocol["Syncmatica Protocol"]:::protocol
            OtherProtocols["AppleSkin & XaeroMap Protocols"]:::protocol
        end

        subgraph "Replay System"
            direction TB
            Recorder["Recorder"]:::impl
            ReplayFile["ReplayFile"]:::impl
            ServerPhotographer["ServerPhotographer"]:::impl
        end

        subgraph "Utility Packages"
            direction TB
            LeafUtil["leaf/util"]:::impl
            LMCUtil["leaves/util"]:::impl
        end
    end

    %% Build Flow
    GradleWrapper --> BuildGradle --> SettingsGradle --> GradleScripts --> PaperweightTasks
    PaperweightTasks --> galePatches --> mcPatches --> paperPatches --> leaf-server

    %% Runtime Flow
    Platform --> LeafBootstrap
    LeafBootstrap --> AsyncLocator
    LeafBootstrap --> ConfigCore
    LeafBootstrap --> LeafCommand
    LeafBootstrap --> LeavesProtocolCore

    %% Subsystem Flows
    AsyncLocator --> PWTEventScheduler
    PWTEventScheduler --> Platform
    ConfigCore --> AsyncLocator
    ConfigCore --> LeafCommand
    ConfigCore --> Lithium

    LeavesProtocolCore --> JadeProtocol
    LeavesProtocolCore --> SyncmaticaProtocol
    LeavesProtocolCore --> OtherProtocols

    SentryManager --> SentryService
    LeafCommand --> bStatsService

    %% Click Events
    click BuildGradle "https://github.com/winds-studio/leaf/blob/ver/1.21.4/build.gradle.kts"
    click SettingsGradle "https://github.com/winds-studio/leaf/blob/ver/1.21.4/settings.gradle.kts"
    click GradleWrapper "https://github.com/winds-studio/leaf/tree/ver/1.21.4/gradle/wrapper/"
    click GradleScripts "https://github.com/winds-studio/leaf/tree/ver/1.21.4/scripts/"
    click leafApi "https://github.com/winds-studio/leaf/tree/ver/1.21.4/leaf-api/"
    click leafApiBuildPatch "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-api/build.gradle.kts.patch"
    click leafApiPatches "https://github.com/winds-studio/leaf/tree/ver/1.21.4/leaf-api/paper-patches/features/"
    click galePatches "https://github.com/winds-studio/leaf/tree/ver/1.21.4/leaf-server/gale-patches/features/"
    click mcPatches "https://github.com/winds-studio/leaf/tree/ver/1.21.4/leaf-server/minecraft-patches/features/"
    click paperPatches "https://github.com/winds-studio/leaf/tree/ver/1.21.4/leaf-server/paper-patches/features/"
    click LeafBootstrap "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/dreeam/leaf/LeafBootstrap.java"
    click AsyncLocator "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/dreeam/leaf/async/locate/AsyncLocator.java"
    click AsyncPath "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/dreeam/leaf/async/path/AsyncPath.java"
    click MultithreadedTracker "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/dreeam/leaf/async/tracker/MultithreadedTracker.java"
    click PWTEventScheduler "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/dreeam/leaf/async/world/PWTEventScheduler.java"
    click ConfigCore "https://github.com/winds-studio/leaf/tree/ver/1.21.4/leaf-server/src/main/java/org/dreeam/leaf/config/"
    click ConfigModules "https://github.com/winds-studio/leaf/tree/ver/1.21.4/leaf-server/src/main/java/org/dreeam/leaf/config/modules/"
    click LeafCommand "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/dreeam/leaf/command/LeafCommand.java"
    click MSPTCommand "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/dreeam/leaf/command/subcommands/MSPTCommand.java"
    click ReloadCommand "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/dreeam/leaf/command/subcommands/ReloadCommand.java"
    click VersionCommand "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/dreeam/leaf/command/subcommands/VersionCommand.java"
    click PufferfishSentryAppender "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/gg/pufferfish/pufferfish/sentry/PufferfishSentryAppender.java"
    click SentryManager "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/gg/pufferfish/pufferfish/sentry/SentryManager.java"
    click Lithium "https://github.com/winds-studio/leaf/tree/ver/1.21.4/leaf-server/src/main/java/net/caffeinemc/mods/lithium/"
    click PurpurAFK "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/purpurmc/purpur/command/AFKCommand.java"
    click LeavesProtocolCore "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/leavesmc/leaves/protocol/core/LeavesProtocol.java"
    click JadeProtocol "https://github.com/winds-studio/leaf/tree/ver/1.21.4/leaf-server/src/main/java/org/leavesmc/leaves/protocol/jade/"
    click SyncmaticaProtocol "https://github.com/winds-studio/leaf/tree/ver/1.21.4/leaf-server/src/main/java/org/leavesmc/leaves/protocol/syncmatica/"
    click OtherProtocols "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/leavesmc/leaves/protocol/AppleSkinProtocol.java"
    click Recorder "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/leavesmc/leaves/replay/Recorder.java"
    click ReplayFile "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/leavesmc/leaves/replay/ReplayFile.java"
    click ServerPhotographer "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/leavesmc/leaves/replay/ServerPhotographer.java"
    click LeafUtil "https://github.com/winds-studio/leaf/tree/ver/1.21.4/leaf-server/src/main/java/org/dreeam/leaf/util/"
    click LMCUtil "https://github.com/winds-studio/leaf/blob/ver/1.21.4/leaf-server/src/main/java/org/leavesmc/leaves/util/UUIDSerializer.java"

    %% Styles
    classDef build fill:#cccccc,stroke:#333,stroke-width:1px
    classDef api fill:#bddbfe,stroke:#333,stroke-width:1px
    classDef impl fill:#c6f6d5,stroke:#333,stroke-width:1px
    classDef async fill:#f6bd60,stroke:#333,stroke-width:1px
    classDef protocol fill:#9d94ff,stroke:#333,stroke-width:1px
    classDef external fill:#ff7f7f,stroke:#333,stroke-width:1px
```
