# segurad/atlasmc architecture

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

- Interactive diagram: https://gitdiagram.com/segurad/atlasmc
- Repository: https://github.com/segurad/atlasmc

## Overview

##### Main “layers” or modules
- Atlas Common Modules – “atlas-common-api” and “atlas-common-core”
– These provide a basic API and core implementations used across the whole system. They include facilities for caching, chat, command parsing, event handling, registry management, scheduler functionality, configuration, and utilities.
- Master (Controller) Modules – “atlas-master-api” and “atlas-master-core”
– These modules manage the overall cluster. Components like AtlasMaster, Proxy/Server management, permission and profile handling, and node management reside here. The master node is responsible for coordinating and resource-handling across the network.
- Network Modules – “atlas-network-api”, “atlas-network-core-common”, “atlas-network-core-master”, and “atlas-network-core-minion”
– They encapsulate the communication protocols and network management. They define APIs and core classes to establish connectivity between Atlas nodes, deal with handshakes, and route packets (including protocol-specific message classes).
- Node Modules – “atlas-node-api”, “atlas-node-bootstrap”, and “atlas-node-core”
– These govern the individual server node’s behavior. In a cluster, each Atlas-Node runs internal “servers” (threads sharing one JVM) and is responsible for node-specific initialization, connection to the master node, and running the local instance of the game server.
- Other modules – such as atlas-packaging, atlas-shade-plugin, and atlas-test, which are used for building, shading (code transformation), and testing respectively.
- Documentation and Test Resources – “doc” and “testresources” directories hold configuration examples (for blocks, protocols, registries) and guidance.

##### Relationships and interactions
- The Common layer sits at the core. Both Master modules and Node modules depend on the common API/core libraries.
- The Master modules use the Network modules to communicate with the nodes. Also, Master modules provide the API layer (in atlas-master-api) that abstracts node management, server start/stop, and configuration distribution.
- The Network modules act as the intermediary for all network communications between master and node. They encapsulate protocol details (handshake, login, play, status) using Netty under the hood.
- The Node modules leverage the Network API and the common API to “bootstrap” servers, load plugins/contentpacks, and to report status and receive commands from the master.
- The design is modular and relies on dependency inversion where higher-level modules (like the master) depend on interfaces defined in the API modules that are implemented in their *-core counterparts.
- The layered separation means that external systems (e.g., plugins, configuration contentpacks) plug into the defined API and are managed by infrastructure modules such as the plugin manager and channel/command system (found in the common and core modules).

##### Important architectural patterns and design principles
- Layered Design: Common APIs at the core, with the Master and Node layers built atop them, and the Network layer encapsulating communications.
- Extension & Plugin Support: The architecture is designed for administrative and development flexibility allowing plugins (or “contentpacks”) and configurable behavior.
- Event-Driven & Protocol-Oriented Patterns: There is extensive event handling (see “event” packages) and protocol handling with dedicated packages for handshake, login, play, and status.

##### Final checklist
- Annotations or callouts for design principles such as “event-driven”, “extensibility”, “protocol integration”.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% External Components
    EXT_Plugins(("Plugins/Contentpacks")):::api

    %% Atlas Master Layer
    subgraph "Atlas Master"
        AM_API(("atlas-master-api")):::api
        AM_Core["atlas-master-core"]:::core
    end

    %% Atlas Common Layer
    subgraph "Atlas Common"
        AC_API(("atlas-common-api")):::api
        AC_Core["atlas-common-core"]:::core
    end

    %% Atlas Node Layer
    subgraph "Atlas Node"
        ANO_API(("atlas-node-api")):::api
        ANO_Bootstrap["atlas-node-bootstrap"]:::core
        ANO_Core["atlas-node-core"]:::core
    end

    %% Atlas Network Layer
    subgraph "Atlas Network"
        AN_API(("atlas-network-api")):::api
        AN_CoreCommon["atlas-network-core-common"]:::core
        AN_CoreMaster["atlas-network-core-master"]:::core
        AN_CoreMinion["atlas-network-core-minion"]:::core
    end

    %% Other Utilities & Build Tools
    subgraph "Other Utilities & Build Tools"
        AU_Packaging["atlas-packaging"]:::misc
        AU_Shade["atlas-shade-plugin"]:::misc
        AU_Test["atlas-test"]:::misc
    end

    %% Documentation and Test Resources
    subgraph "Documentation & Test Resources"
        D_Doc["doc"]:::doc
        D_TestResources["testresources"]:::doc
    end

    %% Relationships

    %% External plugins integrate with Atlas Common API
    EXT_Plugins -->|"plugin_integration"| AC_API

    %% Atlas Master depends on Atlas Common
    AM_API -->|"depends"| AC_API
    AM_API -->|"depends"| AC_Core
    AM_Core -->|"depends"| AC_API
    AM_Core -->|"depends"| AC_Core

    %% Atlas Node depends on Atlas Common
    ANO_API -->|"depends"| AC_API
    ANO_API -->|"depends"| AC_Core
    ANO_Bootstrap -->|"depends"| AC_Core
    ANO_Core -->|"depends"| AC_Core

    %% Master and Node communicate with Atlas Network modules
    AM_API -->|"cluster_comm"| AN_API
    AM_Core -->|"cluster_comm"| AN_CoreMaster
    ANO_API -->|"cluster_comm"| AN_API
    ANO_Bootstrap -->|"cluster_comm"| AN_CoreMinion

    %% Master manages nodes
    AM_Core -->|"node_management"| ANO_Core

    %% Classes for styling
    classDef api fill:#AEDFF7,stroke:#000,stroke-width:2px;
    classDef core fill:#C0E8C0,stroke:#000,stroke-width:2px;
    classDef misc fill:#F7D6AD,stroke:#000,stroke-width:2px;
    classDef doc fill:#FFF2B2,stroke:#000,stroke-width:2px;

    %% Click Events
    click AC_API "https://github.com/segurad/atlasmc/tree/master/atlas-common-api"
    click AC_Core "https://github.com/segurad/atlasmc/tree/master/atlas-common-core"
    click AM_API "https://github.com/segurad/atlasmc/tree/master/atlas-master-api"
    click AM_Core "https://github.com/segurad/atlasmc/tree/master/atlas-master-core"
    click AN_API "https://github.com/segurad/atlasmc/tree/master/atlas-network-api"
    click AN_CoreCommon "https://github.com/segurad/atlasmc/tree/master/atlas-network-core-common"
    click AN_CoreMaster "https://github.com/segurad/atlasmc/tree/master/atlas-network-core-master"
    click AN_CoreMinion "https://github.com/segurad/atlasmc/tree/master/atlas-network-core-minion"
    click ANO_API "https://github.com/segurad/atlasmc/tree/master/atlas-node-api"
    click ANO_Bootstrap "https://github.com/segurad/atlasmc/tree/master/atlas-node-bootstrap"
    click ANO_Core "https://github.com/segurad/atlasmc/tree/master/atlas-node-core"
    click AU_Packaging "https://github.com/segurad/atlasmc/tree/master/atlas-packaging"
    click AU_Shade "https://github.com/segurad/atlasmc/tree/master/atlas-shade-plugin"
    click AU_Test "https://github.com/segurad/atlasmc/tree/master/atlas-test"
    click D_Doc "https://github.com/segurad/atlasmc/tree/master/doc"
    click D_TestResources "https://github.com/segurad/atlasmc/tree/master/testresources"
```
