# horizonsendmc/ion architecture

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

- Interactive diagram: https://gitdiagram.com/horizonsendmc/ion
- Repository: https://github.com/horizonsendmc/ion

## Overview

##### Project type and purpose
- This is a multi-module Gradle Kotlin project that implements a Minecraft network plugin.
- It consists of three modules:
- common – shared library of database, cache, Redis, and utility components
- proxy – a Waterfall/Velocity proxy plugin (IonProxy)
- server – a Paper/Spigot server plugin (IonServer)
- Purpose: on Horizon’s End network, the Proxy plugin handles cross-server commands, Discord integration, and caching; the Server plugin handles world logic, Star Legacy features, and persistent data.

##### File structure
- Top-level modules: common/, proxy/, server/
- run/config/ contains Docker Compose and per-service configs (MongoDB, Paper server, Velocity/Waterfall proxy)
- common module contains: database schema, cache managers, Redis pub/sub, configuration classes, shared utilities
- proxy module relies on Velocity API, uses Redis for messaging & common caches, has Discord and command features
- server module relies on Bukkit/Paper API, uses common DBManager (Mongo), Redis messaging, implements game features (starships, AI, multiblock, transport, etc.)
- build.gradle.kts and Gradle wrapper for build orchestration

##### Key architecture details from README
- Two plugins: IonProxy.jar, IonServer.jar
- Shared foundation: Star Legacy plugin extended
- Test environment spun up via Docker Compose: Velocity/Waterfall proxy, Paper server, MongoDB, Redis

a. Minecraft Clients
b. Network Proxy container (Waterfall/Velocity) hosting IonProxy plugin
c. Game Server container (Paper/Spigot) hosting IonServer plugin
d. common library embedded in both plugins
e. MongoDB (persistent storage)
f. Redis (pub/sub & caches)
g. External Services: Discord API

##### Relationships & interactions
- Clients → Proxy plugin: commands, chat, server-list pings
- Proxy plugin ↔ Redis: publish/subscribe messages, cache population
- Proxy plugin → common: shared DB and util code
- Proxy plugin → Discord: HTTP calls to send messages
- Proxy plugin → backends: plugin messaging channels (Velocity→Paper forwarding)
- Server plugin ↔ Redis: subscribes to forwarded messages, caches data
- Server plugin → MongoDB: load/save schemas via common DBManager
- Server plugin → Discord: HTTP calls via common DiscordConfiguration
- Server plugin → common: shared code for caching, DB, utilities

##### Architectural patterns & principles
- Modular multi-project Gradle build (common, proxy, server)
- Shared library for DRY: “common” module
- Pub/Sub via Redis for decoupling cross-process communication
- Containerized microservices in local test (Docker Compose)
- Plugin messaging and forwarding between proxy and server

##### Technologies & frameworks
- Kotlin, Gradle Kotlin DSL
- Velocity/Waterfall Proxy API
- Paper/Spigot Server API
- MongoDB (NoSQL persistence)
- Redis (cache & messaging)
- Discord HTTP API integration
- Docker & Docker Compose for test environment

##### Detail level
- Major components and how they interact
- Don’t try to show every package or class; focus on module boundaries, data flow, and technology touchpoints
- Redis pub/sub as the decoupling mechanism between Proxy and Server

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Edge
    subgraph "Edge Tier"
        direction TB
        Client["Minecraft Client"]:::client
    end

    %% Proxy Tier
    subgraph "Proxy Tier"
        direction TB
        Proxy["Waterfall/Velocity Proxy\n+ IonProxy"]:::plugin
    end

    %% Backend Tier
    subgraph "Backend Tier"
        direction TB
        Server["Paper/Spigot Server\n+ IonServer"]:::plugin
    end

    %% Shared Common Library
    Common["common Module\n(shared library)"]:::shared

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Redis["Redis\n(pub/sub & cache)"]:::datastore
        Mongo["MongoDB\n(persistent storage)"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Discord["Discord API"]:::external
    end

    %% Flows
    Client -->|"connects & commands"| Proxy
    Proxy -->|"plugin messaging"| Server
    Proxy -->|"pub/sub"| Redis
    Server -->|"pub/sub"| Redis
    Server -->|"read/write"| Mongo
    Proxy -->|"HTTP request"| Discord
    Server -->|"HTTP request"| Discord
    Proxy -->|"uses shared code"| Common
    Server -->|"uses shared code"| Common

    %% Click Events
    click Common "https://github.com/horizonsendmc/ion/tree/main/common/"
    click DBManager "https://github.com/horizonsendmc/ion/blob/main/common/src/main/kotlin/net/horizonsend/ion/common/database/DBManager.kt"
    click RedisPubSub "https://github.com/horizonsendmc/ion/tree/main/common/src/main/kotlin/net/horizonsend/ion/common/redis/"
    click DiscordConfiguration "https://github.com/horizonsendmc/ion/blob/main/common/src/main/kotlin/net/horizonsend/ion/common/utils/discord/DiscordConfiguration.kt"
    click Proxy "https://github.com/horizonsendmc/ion/tree/main/proxy/"
    click IonProxyEntry "https://github.com/horizonsendmc/ion/blob/main/proxy/src/main/kotlin/net/horizonsend/ion/proxy/IonProxy.kt"
    click ProxyComponent "https://github.com/horizonsendmc/ion/blob/main/proxy/src/main/kotlin/net/horizonsend/ion/proxy/IonProxyComponent.kt"
    click ProxyCommands "https://github.com/horizonsendmc/ion/tree/main/proxy/src/main/kotlin/net/horizonsend/ion/proxy/commands/"
    click ProxyFeatures "https://github.com/horizonsendmc/ion/tree/main/proxy/src/main/kotlin/net/horizonsend/ion/proxy/features/"
    click ProxyConfig "https://github.com/horizonsendmc/ion/blob/main/proxy/src/main/kotlin/net/horizonsend/ion/proxy/configuration/ProxyConfiguration.kt"
    click Server "https://github.com/horizonsendmc/ion/tree/main/server/"
    click IonServerEntry "https://github.com/horizonsendmc/ion/blob/main/server/src/main/kotlin/net/horizonsend/ion/server/IonServer.kt"
    click IonBootstrapper "https://github.com/horizonsendmc/ion/blob/main/server/src/main/kotlin/net/horizonsend/ion/server/miscellaneous/IonBootstrapper.kt"
    click IonPluginLoader "https://github.com/horizonsendmc/ion/blob/main/server/src/main/kotlin/net/horizonsend/ion/server/miscellaneous/IonPluginLoader.kt"
    click ServerCommands "https://github.com/horizonsendmc/ion/tree/main/server/src/main/kotlin/net/horizonsend/ion/server/command/"
    click ServerFeatures "https://github.com/horizonsendmc/ion/tree/main/server/src/main/kotlin/net/horizonsend/ion/server/features/"
    click ServerConfig "https://github.com/horizonsendmc/ion/tree/main/server/src/main/kotlin/net/horizonsend/ion/server/configuration/"
    click DockerCompose "https://github.com/horizonsendmc/ion/blob/main/run/docker-compose.yml"
    click MongoInit "https://github.com/horizonsendmc/ion/blob/main/run/config/mongo/mongo-init.js"
    click PaperConfig "https://github.com/horizonsendmc/ion/tree/main/run/config/paper/"
    click VelocityConfig "https://github.com/horizonsendmc/ion/tree/main/run/config/velocity/"
    click WaterfallConfig "https://github.com/horizonsendmc/ion/blob/main/run/config/waterfall/config.yml"

    %% Styles
    classDef client fill:#cccccc,stroke:#333,stroke-width:1px
    classDef plugin fill:#aed4f4,stroke:#333,stroke-width:1px
    classDef shared fill:#cfe2f3,stroke:#333,stroke-width:1px
    classDef datastore fill:#b4f0b4,stroke:#333,stroke-width:1px
    classDef external fill:#f4cba9,stroke:#333,stroke-width:1px
```
