# bluemap-minecraft/bluemap architecture

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

- Interactive diagram: https://gitdiagram.com/bluemap-minecraft/bluemap
- Repository: https://github.com/bluemap-minecraft/bluemap

## Overview

##### Project type and purpose
- BlueMap is a multi-module Java/Kotlin application for reading Minecraft world files, rendering 2D/3D map data, and serving a browser-based frontend.
- It ships as (a) a standalone CLI tool, (b) plugins/mods for various Minecraft servers (Spigot/Paper, Forge, Fabric, Sponge), and (c) an embedded HTTP server + webapp for interactive map viewing.

##### File structure
- Top-level Gradle multi-project (settings.gradle.kts) with subprojects:
- core – the map-generation engine (world parsing, tile & model rendering, storage).
- common – shared services (config management, command framework, HTTP server, addon/plugin API).
- api – interface definitions for external extensions.
- implementations – per-server/serverless deliverables:
· cli – standalone command-line invocation
· fabric, forge, neoforge, paper, spigot, sponge – server mods/plugins forwarding events to BlueMap
- common/webapp – Vue.js + raw JS static frontend (Map Viewer).
- resourceExtensions – default Minecraft assets & JSON resources (blockstates, models, textures).
- buildSrc contains custom Gradle logic (publishing, versioning, copying files).
- Configuration files: gradle.properties, Dockerfile, CI workflows, sample .conf under common/src/main/resources.

##### README for additional insights
- BlueMap reads world files asynchronously, renders 3D geometry, serves via webapp.
- It is extensible: plugin API, addons.
- Features include low-res & high-res rendering, mask configurability, multiple storage backends (file, SQL).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Delivery Layer
    subgraph "Delivery Layer"
        direction TB
        CLI["CLI Tool"]:::delivery
        Fabric["Fabric Mod"]:::delivery
        Forge["Forge Mod"]:::delivery
        NeoForge["NeoForge Mod"]:::delivery
        Paper["Paper Plugin"]:::delivery
        Spigot["Spigot Plugin"]:::delivery
        Sponge["Sponge Plugin"]:::delivery
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        ConfigMgmt["Configuration Management"]:::service
        CommandFW["Command Framework"]:::service
        PluginAPI["Addon/Plugin API"]:::service
        MapUpdate["MapUpdateService"]:::service
        HTTPServer["Embedded HTTP Server & API"]:::service
    end

    %% Engine Layer
    subgraph "Engine Layer"
        direction TB
        WorldInput["World File Input"]:::engine
        CoreEngine["Core Engine"]:::engine
    end

    %% Storage Layer
    subgraph "Storage Layer"
        direction TB
        FileStorage["File Storage"]:::storage
        SQLStorage["SQL Storage"]:::storage
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        WebApp["Web Frontend (Vue.js Map Viewer)"]:::frontend
    end

    %% Build & CI
    subgraph "Build & CI"
        direction TB
        Settings["settings.gradle.kts"]:::build
        BuildSrc["buildSrc"]:::build
        CI[".github/workflows/build.yml"]:::build
        DockerfileNode["Dockerfile"]:::build
    end

    %% Connections
    CLI -->|triggers| MapUpdate
    Fabric -->|forwards events| MapUpdate
    Forge -->|forwards events| MapUpdate
    NeoForge -->|forwards events| MapUpdate
    Paper -->|forwards events| MapUpdate
    Spigot -->|forwards events| MapUpdate
    Sponge -->|forwards events| MapUpdate

    MapUpdate -->|invokes| CoreEngine
    WorldInput -->|reads region files| CoreEngine
    CoreEngine -->|writes tiles/models| FileStorage
    CoreEngine -->|writes tiles/models| SQLStorage

    HTTPServer -->|serves API endpoints| CoreEngine
    HTTPServer -->|reads tiles/models| FileStorage
    HTTPServer -->|reads tiles/models| SQLStorage
    WebApp -->|fetches via HTTP| HTTPServer

    ConfigMgmt --> MapUpdate
    CommandFW --> MapUpdate
    PluginAPI --> MapUpdate

    Settings --> BuildSrc
    Settings --> CI
    Settings --> DockerfileNode

    %% Click Events
    click WorldInput "https://github.com/bluemap-minecraft/bluemap/tree/master/core/src/main/java/de/bluecolored/bluemap/core/world"
    click CoreEngine "https://github.com/bluemap-minecraft/bluemap/tree/master/core/src/main/java/de/bluecolored/bluemap/core"
    click FileStorage "https://github.com/bluemap-minecraft/bluemap/tree/master/core/src/main/java/de/bluecolored/bluemap/core/storage/file"
    click SQLStorage "https://github.com/bluemap-minecraft/bluemap/tree/master/core/src/main/java/de/bluecolored/bluemap/core/storage/sql"
    click ConfigMgmt "https://github.com/bluemap-minecraft/bluemap/tree/master/common/src/main/java/de/bluecolored/bluemap/common/config"
    click CommandFW "https://github.com/bluemap-minecraft/bluemap/tree/master/common/src/main/java/de/bluecolored/bluemap/common/commands"
    click PluginAPI "https://github.com/bluemap-minecraft/bluemap/tree/master/common/src/main/java/de/bluecolored/bluemap/common/addons"
    click PluginAPI "https://github.com/bluemap-minecraft/bluemap/tree/master/common/src/main/java/de/bluecolored/bluemap/common/api"
    click MapUpdate "https://github.com/bluemap-minecraft/bluemap/blob/master/common/src/main/java/de/bluecolored/bluemap/common/plugin/MapUpdateService.java"
    click HTTPServer "https://github.com/bluemap-minecraft/bluemap/tree/master/common/src/main/java/de/bluecolored/bluemap/common/web/http"
    click CLI "https://github.com/bluemap-minecraft/bluemap/tree/master/implementations/cli"
    click Fabric "https://github.com/bluemap-minecraft/bluemap/tree/master/implementations/fabric"
    click Forge "https://github.com/bluemap-minecraft/bluemap/tree/master/implementations/forge"
    click NeoForge "https://github.com/bluemap-minecraft/bluemap/tree/master/implementations/neoforge"
    click Paper "https://github.com/bluemap-minecraft/bluemap/tree/master/implementations/paper"
    click Spigot "https://github.com/bluemap-minecraft/bluemap/tree/master/implementations/spigot"
    click Sponge "https://github.com/bluemap-minecraft/bluemap/tree/master/implementations/sponge"
    click WebApp "https://github.com/bluemap-minecraft/bluemap/tree/master/common/webapp"
    click Settings "https://github.com/bluemap-minecraft/bluemap/blob/master/settings.gradle.kts"
    click BuildSrc "https://github.com/bluemap-minecraft/bluemap/tree/master/buildSrc/src/main/kotlin"
    click CI "https://github.com/bluemap-minecraft/bluemap/blob/master/.github/workflows/build.yml"
    click DockerfileNode "https://github.com/bluemap-minecraft/bluemap/tree/master/Dockerfile"

    %% Styles
    classDef delivery fill:#e6ffe6,stroke:#00aa00
    classDef service fill:#e6f0ff,stroke:#0066cc
    classDef engine fill:#fff0e6,stroke:#cc6600
    classDef storage fill:#f2f2f2,stroke:#666666
    classDef frontend fill:#e6ffff,stroke:#00aaaa
    classDef build fill:#f9f9f2,stroke:#aaaa00
```
