# alex3025/useful-additions architecture

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

- Interactive diagram: https://gitdiagram.com/alex3025/useful-additions
- Repository: https://github.com/alex3025/useful-additions

## Overview

##### Project type and purpose
- This is a Minecraft Forge mod—an extension/plugin for the Minecraft game engine.
- Its purpose is to introduce new blocks, machines, items, GUIs and related logic (“Useful Additions”) to make in-game tasks easier.

##### File structure
- Entry point: com/rgbcraft/usefuladditions/UsefulAdditions.java
- Packages group by responsibility:
– api: shared interfaces and registries for blocks/items
– blocks, items, liquids: domain objects
– tiles: tile-entity implementations (stateful machines)
– containers + guis: server-side inventories and client-side screens (MVC pattern)
– renderers, models, assets: client rendering pipeline
– network: custom packet dispatch and sync
– handlers: event-bus subscribers (config, recipes, world gen, GUI, sounds, achievements)
– proxies: CommonProxy vs ClientProxy (proxy pattern for side-specific code)
– compat: integration adapters for Buildcraft, GregTech
– utils: shared helper classes
- Build/deployment hints: mcmod.info, .gitignore, GitHub workflows

##### README for additional insights
- Confirms project goal (“Useful things and machines”)
- Roadmap link and credits—no impact on architecture

a. Main components
– Minecraft Engine (Forge)
– UsefulAdditions Mod Core (mod entry, lifecycle hooks)
– Side-Specific Proxies (CommonProxy, ClientProxy)
– Event Handlers (ConfigHandler, RecipesHandler, WorldGenHandler, etc.)
– Registry Modules (Blocks.java, Items.java, Liquids.java)
– Tile Entities (machines, e.g., TileOsmosisGenerator)
– Container & GUI Layer (ContainerBase ↔ Gui classes)
– Network Layer (NetworkHandler, INetworkMember)
– Rendering Layer (RenderSmartSafe, models, textures)
– Compatibility Adapters (BuildcraftCompat, GregTechCompat)
– Assets (textures, GUIs, models)

b. Relationships and interactions
– On startup, the Mod Core uses Forge’s event bus to register blocks/items/liquids via registry modules
– Handlers subscribe to preInit, init, postInit events to set up configs, recipes, world generation
– Proxy pattern directs rendering (client only) vs logic (common) into proper side
– Tile Entities hold machine state; Container classes expose inventories to GUIs
– GUI components communicate user actions back to server via NetworkHandler packets
– Compatibility adapters hook into the same lifecycle after core registration
– Assets (located under assets/) are loaded by Forge’s resource manager when needed

c. Architectural patterns and design principles
– Proxy Pattern: separate client-only and common logic
– Event-Driven Architecture: handlers register to Forge event bus
– MVC for GUIs: tile entity = model, container = controller, GUI = view
– Component Registry: central registries for blocks/items/liquids
– Extensibility Points: api package and compat adapters

d. Relevant technologies, frameworks, or libraries
– Java 8+
– Minecraft Forge API
– Gradle (implied by standard Forge project layout)
– GitHub Actions (code scanning via codeql-analysis.yml)
– Third-party mod APIs (Buildcraft, GregTech)

##### Detail
- Lifecycle hooks and message paths.
- Don’t over-abstract—show the raw components (blocks, items, tiles, GUIs, assets, network) and how they connect.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External
    subgraph "Minecraft Engine / Forge API"
    end

    %% Mod Core
    UA["UsefulAdditions Mod Core"]:::core
    click UA "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/UsefulAdditions.java"

    %% Proxies
    subgraph "Proxies"
        CP["CommonProxy"]:::proxy
        click CP "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/proxies/CommonProxy.java"
        CLP["ClientProxy"]:::proxy
        click CLP "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/proxies/ClientProxy.java"
    end

    %% Event Handlers
    subgraph "Event Handlers"
        CH["ConfigHandler"]:::handler
        click CH "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/handlers/ConfigHandler.java"
        RH["RecipesHandler"]:::handler
        click RH "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/handlers/RecipesHandler.java"
        WH["WorldGenHandler"]:::handler
        click WH "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/handlers/WorldGenHandler.java"
        GH["GuiHandler"]:::handler
        click GH "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/handlers/GuiHandler.java"
        SH["SoundHandler"]:::handler
        click SH "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/handlers/SoundHandler.java"
        AH["AchievementsHandler"]:::handler
        click AH "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/handlers/AchievementsHandler.java"
    end

    %% Registries
    subgraph "Registries"
        BR["Blocks (API)"]:::registry
        click BR "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/api/Blocks.java"
        IR["Items (API)"]:::registry
        click IR "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/api/Items.java"
        LR["Liquids"]:::registry
        click LR "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/liquids/Liquids.java"
    end

    %% Domain Objects
    subgraph "Domain Objects"
        B["Blocks"]:::domain
        click B "https://github.com/alex3025/useful-additions/tree/main/com/rgbcraft/usefuladditions/blocks/"
        I["Items"]:::domain
        click I "https://github.com/alex3025/useful-additions/tree/main/com/rgbcraft/usefuladditions/items/"
        LQ["Liquids"]:::domain
        click LQ "https://github.com/alex3025/useful-additions/tree/main/com/rgbcraft/usefuladditions/liquids/"
    end

    %% Tile Entities
    subgraph "Tile Entities"
        T["Tile Entities"]:::tile
        click T "https://github.com/alex3025/useful-additions/tree/main/com/rgbcraft/usefuladditions/tiles/"
    end

    %% Container & GUI
    subgraph "Container & GUI"
        CN["Container Layer"]:::container
        click CN "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/containers/ContainerBase.java"
        GU["GUI Layer"]:::gui
        click GU "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/guis/GuiOsmosisGenerator.java"
    end

    %% Network
    subgraph "Network"
        NH["NetworkHandler"]:::network
        click NH "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/network/NetworkHandler.java"
        NM["INetworkMember"]:::network
        click NM "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/network/INetworkMember.java"
    end

    %% Rendering
    subgraph "Rendering"
        RR["Renderers"]:::render
        click RR "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/renderers/RenderSmartSafe.java"
        MD["Models"]:::render
        click MD "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/models/ModelSmartSafe.java"
        AS["Assets"]:::render
        click AS "https://github.com/alex3025/useful-additions/tree/main/com/rgbcraft/usefuladditions/assets/"
    end

    %% Compatibility
    subgraph "Compatibility Adapters"
        BC["BuildcraftCompat"]:::compat
        click BC "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/compat/BuildcraftCompat.java"
        GT["GregTechCompat"]:::compat
        click GT "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/compat/GregTechCompat.java"
    end

    %% Utilities
    subgraph "Utilities"
        U["Utils"]:::utils
        click U "https://github.com/alex3025/useful-additions/blob/main/com/rgbcraft/usefuladditions/utils/Utils.java"
    end

    %% Relationships
    MinecraftEngine[/Forge API/] --> UA
    UA --> CP
    UA --> CLP
    UA --> CH
    UA --> RH
    UA --> WH
    UA --> GH
    UA --> SH
    UA --> AH
    UA --> BR
    UA --> IR
    UA --> LR
    UA --> BC
    UA --> GT

    BR --> B
    IR --> I
    LR --> LQ

    CP --> RR
    CP --> MD
    CP --> AS
    CLP --> RR
    CLP --> MD
    CLP --> AS

    B --> T
    I --> T
    LQ --> T

    T --> CN
    CN --> GU
    GU --> NH
    NH --> UA
    NM --> T
    NM --> CN

    %% Styles
    classDef external fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef core fill:#ffd699,stroke:#b36b00,stroke-width:2px
    classDef proxy fill:#c2f0c2,stroke:#267326,stroke-width:2px
    classDef handler fill:#ffcccc,stroke:#b30000,stroke-width:1px
    classDef registry fill:#e6e6ff,stroke:#3333cc,stroke-width:1px
    classDef domain fill:#fff2cc,stroke:#cc9900,stroke-width:1px
    classDef tile fill:#d9d9d9,stroke:#595959,stroke-width:1px
    classDef container fill:#ccf2f2,stroke:#008080,stroke-width:1px
    classDef gui fill:#f2ccff,stroke:#800080,stroke-width:1px
    classDef network fill:#ccffcc,stroke:#339933,stroke-width:1px
    classDef render fill:#ffd9b3,stroke:#b36b00,stroke-width:1px
    classDef compat fill:#e6ccff,stroke:#6600cc,stroke-width:1px
    classDef utils fill:#d9edf7,stroke:#31708f,stroke-width:1px
```
