# figt/mesh architecture

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

- Interactive diagram: https://gitdiagram.com/figt/mesh
- Repository: https://github.com/figt/mesh

## Overview

##### Project type and purpose
- This is a Java library (distributed via Maven Central) that provides a Spigot‐based abstraction over CompletableFuture, letting plugin authors “mesh” together asynchronous and synchronous tasks in a pipeline while automatically switching thread contexts.
- Evidence: pom.xml (Maven project), src/main/java/us/figt/mesh, plugin.yml (Spigot plugin descriptor), README description.

##### File structure
- Top level:
- .github/ – CI and issue templates
- pom.xml – Maven build config
- src/main/java/us/figt/mesh – core library code
- src/main/java/us/figt/mesh/example – sample plugin to illustrate usage
- src/main/resources/plugin.yml – plugin metadata
- Core packages:
- mesh – Mesh.java (public API), MeshRunnables.java (task definitions)
- utils – PluginUtil.java (loader/initialization), ThreadContext.java (enum for SYNC vs ASYNC)
- No frontend, no external microservices, purely an embeddable library/plugin.

##### Extract additional insights from README
- Mesh is intended to be shaded & relocated to avoid dependency conflicts.
- Usage revolves around constructing a mesh of tasks (like CompletableFuture chains) where each stage can be executed on a different thread context (main thread or async thread via Bukkit scheduler).

a. Mesh Library Core
- Mesh API (Mesh.java)
- MeshRunnables (defines units of work)
- ThreadContext (SYNC, ASYNC)
- PluginUtil (initializes context, registers scheduler hooks)
b. Spigot Server (external service)
- BukkitScheduler (schedules sync/async tasks)
- Server main thread
c. Example Plugin (us.figt.mesh.example)
- Consumes Mesh API to define a task graph
d. End user / plugin author code (builds mesh pipelines)

##### Relationships and interactions
- Plugin author code → calls Mesh API to create a Mesh instance.
- Mesh internally uses MeshRunnables and ThreadContext to break down the pipeline.
- For each stage: Mesh invokes PluginUtil to hand off runnable to BukkitScheduler, using ThreadContext to pick sync or async queue.
- BukkitScheduler routes tasks to the server main thread or background worker threads.
- Completion of one stage triggers the next stage in the pipeline until the mesh is drained.

##### Architectural patterns and design principles
- Fluent‐style / builder pattern for composing tasks.
- Adapter/facade over Java’s CompletableFuture + Bukkit scheduler.
- Separation of concerns: core library vs external scheduler vs example usage.
- Lightweight, embeddable plugin model.

##### Technologies, frameworks, libraries
- Java 8+ (CompletableFuture)
- Spigot API (BukkitScheduler)
- Maven for build and dependency management
- Optional shading via Maven Shade Plugin

- “Example Plugin” (user code)
- “Mesh API”
- “MeshRunnables & ThreadContext”
- “PluginUtil”
- “BukkitScheduler”
- “Server Main Thread” and “Async Thread Pool”
- From Example Plugin → Mesh API → internal utils → BukkitScheduler → thread pools.
- From thread pools back into Mesh to trigger next stage.
- Green for user/plugin code
- Blue for library internals
- Orange for external Spigot components
- Rectangles for services and libraries

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph: Plugin Author Code
    subgraph "Plugin Author Code"
        direction TB
        ExamplePlugin["ExamplePlugin (user code)"]:::user
    end

    %% Subgraph: Mesh Library Internals
    subgraph "Mesh Library Internals"
        direction TB
        MeshAPI["Mesh API"]:::library
        MeshRunnables["MeshRunnables (task definitions)"]:::library
        ThreadContext["ThreadContext (SYNC/ASYNC)"]:::library
        PluginUtil["PluginUtil (init & scheduler hooks)"]:::library
        PluginMetadata["plugin.yml (metadata)"]:::library
    end

    %% Subgraph: Spigot Server Runtime
    subgraph "Spigot Server Runtime"
        direction TB
        BukkitScheduler["BukkitScheduler"]:::external
        ServerMainThread["Server Main Thread"]:::external
        AsyncThreadPool["Async Thread Pool"]:::external
    end

    %% Subgraph: Documentation & Build
    subgraph "Documentation & Build"
        direction TB
        MavenConfig["pom.xml"]:::docs
        README["README.md"]:::docs
    end

    %% Connections
    ExamplePlugin -->|"calls createMesh()"| MeshAPI
    MeshAPI -->|"defines stages via"| MeshRunnables
    MeshAPI -->|"uses context from"| ThreadContext
    MeshAPI -->|"initializes via"| PluginUtil
    PluginUtil -->|"loads"| PluginMetadata
    PluginUtil -->|"calls scheduleSyncTask()"| BukkitScheduler
    PluginUtil -->|"calls scheduleAsyncTask()"| BukkitScheduler
    BukkitScheduler -->|"runs on"| ServerMainThread
    BukkitScheduler -->|"runs on"| AsyncThreadPool
    ServerMainThread -->|"onComplete triggers"| MeshAPI
    AsyncThreadPool -->|"onComplete triggers"| MeshAPI

    %% Click Events
    click MeshAPI "https://github.com/figt/mesh/blob/master/src/main/java/us/figt/mesh/Mesh.java"
    click MeshRunnables "https://github.com/figt/mesh/blob/master/src/main/java/us/figt/mesh/MeshRunnables.java"
    click ThreadContext "https://github.com/figt/mesh/blob/master/src/main/java/us/figt/mesh/utils/ThreadContext.java"
    click PluginUtil "https://github.com/figt/mesh/blob/master/src/main/java/us/figt/mesh/utils/PluginUtil.java"
    click ExamplePlugin "https://github.com/figt/mesh/blob/master/src/main/java/us/figt/mesh/example/ExamplePlugin.java"
    click PluginMetadata "https://github.com/figt/mesh/blob/master/src/main/resources/plugin.yml"
    click MavenConfig "https://github.com/figt/mesh/blob/master/pom.xml"
    click README "https://github.com/figt/mesh/blob/master/README.md"

    %% Styles
    classDef user fill:#a8f0c6,stroke:#333,stroke-width:1px
    classDef library fill:#c6d8f0,stroke:#333,stroke-width:1px
    classDef external fill:#f0c68c,stroke:#333,stroke-width:1px
    classDef docs fill:#e0e0e0,stroke:#333,stroke-width:1px
```
