# blushiemagic/magicstorage architecture

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

- Interactive diagram: https://gitdiagram.com/blushiemagic/magicstorage
- Repository: https://github.com/blushiemagic/magicstorage

## Overview

##### Project Type & Purpose
- This is a game mod (specifically for Terraria via tModLoader) that introduces a new “magic storage” system to provide a central storage network with extensive UI and crafting functionalities.
- The mod not only organizes items into one central block but also includes features like crafting, decrafting, combined crafting stations, and multi-access points, as well as integrations (e.g., with SerousCommonLib).

##### File Structure
- Top-Level Separation:
- Core System Logic: Files like MagicStorage.cs, MagicStorageMod.cs, and MagicStorageConfig.cs form the mod’s entry point and configuration.
- Common: Contains underlying frameworks such as IO utilities (e.g., BitBuffer128, ValueReader/Writer), threading work managers, global tools, and various systems (magic recipes, recurrent recipes, shimmering systems) that drive the core functionality.
- Components: Consists of game-behavior elements (e.g., StorageAccess, StorageComponent, StorageHeart) and tile entities (TE-prefixed items) that represent the physical or in-game interactive parts.
- Items: Defines the in-game items (storage units, upgrades, and other interactable items) that the player will use.
- UI: Provides a detailed separation between in-game interfaces like CraftingGUI, DecraftingGUI, and other UI components; also contains UI States, input handlers, and history tracking.
- CrossMod and Edits: These directories hint at integration or modification of game behaviors (detours, hooks, custom module integrations) which allow the mod to extend or harmonize with other systems.
- Additional directories like Modules, NPCs, Sorting, and Stations further encapsulate specialized functionality (e.g., combined crafting stations, sorting mechanisms).

a. Core/Entry Module:
- Configuration management (MagicStorageConfig.cs) and project-level solution files.

b. Core Systems & Shared Libraries:
- Common directory components: systems for threading, IO, network communications (Netcode.cs), and magic recipes (MagicRecipes.cs, RecurrentRecipes).
- Dependencies or integration with external libraries such as SerousCommonLib, .NET 6, and the Microsoft XNA Framework Redistributable.

c. UI Layer:
- That the UI layer communicates with core systems to fetch data (like stored items, crafting recipes, searching/filtering operations) and passes user actions down to the business logic layer (via event handlers or command processing).

d. Game Components and Items:
- Separate the in-game components (Components/ folder) that represent functional entities in the world (like different types of storage and access points).
- Items which directly relate to the physical manifestations players interact with.
- Interactions between these components and the core systems (for instance, the components use systems defined in Common/Systems for processing, and UI elements trigger changes in these items).

e. Integration & Extension Mechanisms:
- CrossMod and Edits directories as middleware/adapters that modify or hook into default behaviors. They interface both with the core systems and the game engine (via tModLoader).
- Modules that add on extra functionality, enhancing the mod’s base features.

##### Architectural Patterns & Design Principles
- Layered Architecture: There is a natural separation between the UI, core logic (Common), and the physical game components (Components/Items). Represent these layers distinctly.
- Modular Organization: Features like crafting, decrafting, and storage access are implemented in separate modules (e.g., in UI/GUIs, Components, and Systems); illustrate these as independent yet interacting modules.
- Event-Driven & Command-Based: The existence of Commands and event-related files (like GUI tooltips and Input elements) hint at patterns where user and system actions are communicated via clearly defined messages.
- Extensibility: The CrossMod and Edits folders show hooks and detours that allow the mod to intercept and modify behavior, so include connectors showing external integration points.

##### Final Touches
- You may also consider grouping related functionalities (like grouping all recurrent recipe functionalities together and indicating they interact with crafting-related UI components).
- That every functional module (like network processing, threading, IO utilities, and UI state management) is represented.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core/Entry Module
    subgraph "Core/Entry Module"
        A1["MagicStorageMod.cs"]:::entry
        A2["MagicStorageConfig.cs"]:::entry
        A3["MagicStorage.cs"]:::entry
    end

    %% Core Systems & Shared Libraries
    subgraph "Core Systems & Shared Libraries"
        B1["Common/Systems"]:::core
        B2["Common/IO"]:::core
        B3["Common/Threading"]:::core
        B4["Common/Global"]:::core
    end

    %% UI Layer
    subgraph "UI Layer"
        C1["UI/GUIs"]:::ui
        C2["UI/States"]:::ui
        C3["UI/Input"]:::ui
        C4["UI/History"]:::ui
        C5["UI/Shimmer"]:::ui
        C6["CraftingGUI.cs"]:::ui
        C7["DecraftingGUI.cs"]:::ui
        C8["StorageGUI.cs"]:::ui
    end

    %% Game Components and Items
    subgraph "Game Components and Items"
        D1["Components"]:::game
        D2["Items"]:::game
    end

    %% Integration & Extension Mechanisms
    subgraph "Integration & Extension Mechanisms"
        E1["CrossMod"]:::integration
        E2["Edits"]:::integration
    end

    %% Additional Modules/Features
    subgraph "Additional Modules/Features"
        F1["Modules"]:::modules
    end

    %% Specialized Functionality
    subgraph "Specialized Functionality"
        G1["Stations"]:::modules
        G2["Sorting"]:::modules
        G3["TagHandlers"]:::modules
    end

    %% External Dependencies
    H1["External Libraries (SerousCommonLib,tModLoader,XNA)"]:::integration

    %% Connections: Entry Module to Core Systems
    A1 -->|"init"| B1
    A1 --> B2
    A1 --> B3
    A1 --> B4

    %% Connections: Core Systems directing flow
    B1 -->|"triggers"| C1
    B1 --> D1
    B2 --> D1
    B3 --> B1
    B4 --> D2

    %% Connections: UI interactions with Core
    C1 -->|"commands"| B1
    C2 --> B1
    C3 --> B1
    C6 -->|"craft_actions"| B1
    C7 -->|"decraft_actions"| B1
    C8 --> B1

    %% Connections: Game Components interacting with Core
    D1 -->|"state_update"| B1
    D2 --> B1
    C1 -->|"display_items"| D2

    %% Connections: Integration points
    E1 -->|"hooks"| B1
    E1 --> D1
    E2 -->|"detours"| B1

    %% Connections: Additional Modules and Specialized Functionality enhancements
    F1 -->|"enhancement"| B1
    G1 --> D1
    G2 --> D2
    G3 --> B1

    %% External Dependencies link
    H1 --> B1
    H1 --> C1
    H1 --> D1

    %% Click Events for Components
    click A1 "https://github.com/blushiemagic/magicstorage/blob/1.4.4/MagicStorageMod.cs"
    click A2 "https://github.com/blushiemagic/magicstorage/blob/1.4.4/MagicStorageConfig.cs"
    click A3 "https://github.com/blushiemagic/magicstorage/blob/1.4.4/MagicStorage.cs"
    click B1 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/Common/Systems"
    click B2 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/Common/IO"
    click B3 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/Common/Threading"
    click B4 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/Common/Global"
    click C1 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/UI"
    click C2 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/UI/States"
    click C3 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/UI/Input"
    click C4 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/UI/History"
    click C5 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/UI/Shimmer"
    click C6 "https://github.com/blushiemagic/magicstorage/blob/1.4.4/CraftingGUI.cs"
    click C7 "https://github.com/blushiemagic/magicstorage/blob/1.4.4/DecraftingGUI.cs"
    click C8 "https://github.com/blushiemagic/magicstorage/blob/1.4.4/StorageGUI.cs"
    click D1 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/Components"
    click D2 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/Items"
    click E1 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/CrossMod"
    click E2 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/Edits"
    click F1 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/Modules"
    click G1 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/Stations"
    click G2 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/Sorting"
    click G3 "https://github.com/blushiemagic/magicstorage/tree/1.4.4/TagHandlers"

    %% Styles
    classDef entry fill:#C1F7C1,stroke:#2E7D32,stroke-width:2px;
    classDef core fill:#A3E4D7,stroke:#1ABC9C,stroke-width:2px;
    classDef ui fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef game fill:#F9E79F,stroke:#D68910,stroke-width:2px;
    classDef integration fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef modules fill:#F2F3F4,stroke:#7F8C8D,stroke-width:2px;
```
