# talia-12/hexal architecture

> Architecture diagram of the GitHub repository talia-12/hexal, 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/talia-12/hexal
- Repository: https://github.com/talia-12/hexal

## Overview

##### Main Components
- Common Module – This is the heart of the project and contains the shared APIs, core casting actions, pattern definitions, network messages, data generation, and utility classes. It includes packages for API endpoints (e.g., spell, everbook, gates, linkable, nbt), events, casting actions (both standard and “great spells”), data providers (datagen), and interop with documentation (patchouli books).
- Platform-Specific Implementations – Two major subprojects:
– Fabric Module: Contains Fabric-specific initializers, client renderers, networking, and interop code. It adapts the core mod for Fabric’s mod loader and Minecraft’s client/server architecture.
– Forge Module: Contains corresponding Forge adapters, initializers, event handlers, mixins, client renderers, and network handlers for Forge compatibility.
- Resources and Data – Resources such as block models, textures, animations, language files, data (recipes, advancements, loot tables), and Patchouli book definitions. These assets form part of the mod’s visual and gameplay configuration.
- Tests – A unit testing suite placed under Common/src/test, ensuring integrity for casting actions and other components.
- Build and Configuration – Gradle build scripts, CI configurations (GitHub workflows), and mod configuration files that allow proper compilation and packaging for release.
- External Dependencies – Although not detailed in the file tree, the README mentions dependencies on Hex Casting. Visualizing where Hexal “plugs into” an already-running Hex Casting framework (as well as Minecraft’s mod ecosystem) is essential.

##### Relationships and Interactions
- The Common module serves as the central hub. Both the Fabric and Forge modules depend on “Common” as they implement platform-specific behavior while reusing common business logic.
- There’s a clear boundary between client and server logic:
– The client parts (e.g., client rendering, network packets, client-side configurations in Fabric/Forge) interact with the common APIs via networking and event handlers.
– The server-side or shared logic (casting actions, configuration, level generation) on Common feeds into both platform-specific parts.
- External interactions include:
– Minecraft’s underlying game engine.
– Possibly external tools (Patchouli book integration for in-game documentation).

##### Architectural Patterns and Design Principles
- Cross-Platform Abstraction: Notice the xplat packages (e.g., IClientXplatAbstractions, IXplatAbstractions) that define contracts to be implemented differently on Fabric and Forge.
- Modular Design: Separation into Common, Fabric, and Forge illustrates a classic modular approach, where shared logic is decoupled from platform-specific code.
- Event-Driven and Network Messaging: There are packages annotated for network messages (e.g., MsgAddRenderLinkAck, MsgWispCastSoundAck) and event handlers (e.g., EverbookEventHandler), suggesting reactive programming patterns.
- API Exposure and Extensibility: The numerous API packages (spell, linkable, extended casting actions) indicate a design built to be extensible for additional casting or mod functionality.

##### Detailed and Precise Representation
- Service boundaries showing how the mod utilizes interop packages (xplat) to abstract differences.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Systems
    ME["Minecraft Engine"]:::external
    HC["Hex Casting Mod"]:::external

    %% Build and Test
    BuildConfig["Build & Config"]:::config
    Tests["Unit Tests"]:::test

    %% Platform-specific Modules
    FabricModule["Fabric Module"]:::platform
    ForgeModule["Forge Module"]:::platform

    %% Common Module (Main)
    CommonModule["Common Module"]:::common

    %% Common Module Internals
    subgraph "Common Internals"
        APIEndpoints["API Endpoints"]:::common
        CastingActions["Casting Actions & Patterns"]:::common
        NetworkMessages["Network Messages"]:::common
        DataGeneration["Data Generation"]:::common
        PatchouliInterop["Patchouli Documentation Interop"]:::common
        XplatAbstraction["Cross-Platform Abstraction"]:::common
    end

    %% Resources & Data Assets
    CommonResources["Common Resources & Data"]:::resource
    FabricResources["Fabric Generated Resources"]:::resource
    ForgeResources["Forge Generated Resources"]:::resource

    %% Relationships - External to Common
    ME -->|"integrates_with"| CommonModule
    HC -->|"extends"| CommonModule

    %% Platform Modules depend on Common
    FabricModule -->|"depends_on"| CommonModule
    ForgeModule -->|"depends_on"| CommonModule

    %% Common Module contains internal components
    CommonModule -->|"contains"| APIEndpoints

    %% Build system builds modules
    BuildConfig -->|"builds"| CommonModule
    BuildConfig -->|"builds"| FabricModule
    BuildConfig -->|"builds"| ForgeModule

    %% Testing
    Tests -->|"tests"| CommonModule

    %% Resource relationships
    APIEndpoints -->|"loads_assets_from"| CommonResources
    FabricModule -->|"generates_assets"| FabricResources
    ForgeModule -->|"generates_assets"| ForgeResources

    %% Class Definitions for styling
    classDef common fill:#FFCCCC,stroke:#990000,stroke-width:2px;
    classDef platform fill:#CCFFCC,stroke:#006600,stroke-width:2px;
    classDef external fill:#FFFFCC,stroke:#999900,stroke-width:2px;
    classDef resource fill:#FFEEAA,stroke:#CC9900,stroke-width:2px;
    classDef test fill:#D5E8D4,stroke:#82B366,stroke-width:2px;
    classDef config fill:#E0E0E0,stroke:#666666,stroke-width:2px;

    %% Click Events
    click CommonModule "https://github.com/talia-12/hexal/tree/main/Common/src/main/java/ram/talia/hexal"
    click APIEndpoints "https://github.com/talia-12/hexal/tree/main/Common/src/main/java/ram/talia/hexal/api"
    click CastingActions "https://github.com/talia-12/hexal/tree/main/Common/src/main/java/ram/talia/hexal/common/casting"
    click NetworkMessages "https://github.com/talia-12/hexal/tree/main/Common/src/main/java/ram/talia/hexal/common/network"
    click DataGeneration "https://github.com/talia-12/hexal/tree/main/Common/src/main/java/ram/talia/hexal/datagen"
    click PatchouliInterop "https://github.com/talia-12/hexal/tree/main/Common/src/main/java/ram/talia/hexal/interop/patchouli"
    click XplatAbstraction "https://github.com/talia-12/hexal/tree/main/Common/src/main/java/ram/talia/hexal/xplat"
    click FabricModule "https://github.com/talia-12/hexal/tree/main/Fabric/src/main/java/ram/talia/hexal/fabric"
    click ForgeModule "https://github.com/talia-12/hexal/tree/main/Forge/src/main/java/ram/talia/hexal/forge"
    click CommonResources "https://github.com/talia-12/hexal/tree/main/Common/src/main/resources/assets/hexal"
    click FabricResources "https://github.com/talia-12/hexal/tree/main/Fabric/src/generated/resources"
    click ForgeResources "https://github.com/talia-12/hexal/tree/main/Forge/src/generated/resources"
    click Tests "https://github.com/talia-12/hexal/tree/main/Common/src/test"
    click BuildConfig "https://github.com/talia-12/hexal/blob/main/build.gradle"
```
