# expressobits/inventory-system architecture

> Architecture diagram of the GitHub repository expressobits/inventory-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/expressobits/inventory-system
- Repository: https://github.com/expressobits/inventory-system

## Overview

Expresso Inventory System is a Godot C++ plugin providing reusable inventory, item, crafting, loot, and editor tooling. A typical gameplay flow stores item stacks in an inventory, optionally applies constraints or grid placement, and exposes supporting hotbar, loot-generation, and crafting capabilities. The editor plugin manages database resources for items, categories, recipes, stations, and loot. Relationships below are limited to README statements and SOURCE INDEX references; unsampled implementations are represented by their known source paths without inferred call chains.

Main entry points: [`src/base/inventory_database.h`](https://github.com/expressobits/inventory-system/blob/main/src/base/inventory_database.h) (Inventory database), [`src/core/inventory.h`](https://github.com/expressobits/inventory-system/blob/main/src/core/inventory.h) (Inventory), [`src/craft/craft_station.h`](https://github.com/expressobits/inventory-system/blob/main/src/craft/craft_station.h) (Craft station), [`src/base/node_inventories.h`](https://github.com/expressobits/inventory-system/blob/main/src/base/node_inventories.h) (Node inventories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_resources["Item resources"]
  node_item_definition["Item definitions<br/>[item_definition.h]"]
  node_item_category["Item categories<br/>[item_category.h]"]
  node_item_stack["Item stacks<br/>[item_stack.h]"]
  node_recipe["Recipes<br/>[recipe.h]"]
  node_station_type["Station types"]
  node_loot["Loot resources<br/>[loot.h]"]
  node_database[("Inventory database")]
end

subgraph group_runtime["Inventory runtime"]
  node_inventory["Inventory<br/>[inventory.h]"]
  node_constraints["Inventory constraints"]
  node_grid_inventory["Grid inventory<br/>[grid_inventory.h]"]
  node_grid_constraints["Grid constraints"]
  node_quad_tree["Grid spatial index<br/>[quad_tree.h]"]
  node_node_inventories["Node inventories<br/>[node_inventories.h]"]
end

subgraph group_gameplay["Gameplay systems"]
  node_hotbar["Hotbar<br/>[hotbar.h]"]
  node_loot_generator["Loot generator<br/>[loot_generator.h]"]
  node_craft_station["Craft station<br/>[craft_station.h]"]
end

subgraph group_editor["Database editor"]
  node_editor_plugin["Inventory editor"]
  node_item_editor["Item editor"]
  node_recipe_editor["Recipe editor<br/>[recipe_editor.cpp]"]
  node_loot_item_editor["Loot item editor"]
  node_stack_selector["Stack selector"]
end

node_actor(("Game logic"))

node_actor -.->|"manages items"| node_inventory
node_inventory -->|"stores stacks"| node_item_stack
node_inventory -->|"checks rules"| node_constraints
node_grid_inventory -->|"extends"| node_inventory
node_grid_inventory -->|"indexes spaces"| node_quad_tree
node_grid_inventory -->|"checks placement"| node_grid_constraints
node_node_inventories -->|"references"| node_database
node_node_inventories -->|"references"| node_item_definition
node_hotbar -->|"uses inventory"| node_inventory
node_hotbar -->|"uses node inventories"| node_node_inventories
node_database -->|"catalogs"| node_item_definition
node_database -->|"catalogs"| node_item_category
node_database -->|"catalogs"| node_recipe
node_database -->|"catalogs"| node_station_type
node_database -->|"catalogs"| node_loot
node_recipe -->|"identifies station"| node_station_type
node_recipe -->|"uses stacks"| node_item_stack
node_loot -.->|"edited by"| node_loot_item_editor
node_craft_station -->|"uses type"| node_station_type
node_craft_station -->|"uses database"| node_database
node_craft_station -->|"inherits"| node_node_inventories
node_craft_station -->|"uses inventories"| node_inventory
node_editor_plugin -->|"manages"| node_database
node_editor_plugin -->|"opens editor"| node_recipe_editor
node_editor_plugin -->|"opens editor"| node_item_editor
node_item_editor -->|"edits resources"| node_database
node_item_editor -->|"uses selector"| node_stack_selector
node_recipe_editor -->|"edits resources"| node_database
node_recipe_editor -->|"uses selector"| node_stack_selector
node_loot_item_editor -->|"edits loot"| node_database
node_loot_item_editor -->|"uses selector"| node_stack_selector

click node_item_definition "https://github.com/expressobits/inventory-system/blob/main/src/base/item_definition.h"
click node_item_category "https://github.com/expressobits/inventory-system/blob/main/src/base/item_category.h"
click node_item_stack "https://github.com/expressobits/inventory-system/blob/main/src/base/item_stack.h"
click node_recipe "https://github.com/expressobits/inventory-system/blob/main/src/base/recipe.h"
click node_station_type "https://github.com/expressobits/inventory-system/blob/main/src/base/craft_station_type.h"
click node_loot "https://github.com/expressobits/inventory-system/blob/main/src/base/loot.h"
click node_database "https://github.com/expressobits/inventory-system/blob/main/src/base/inventory_database.h"
click node_inventory "https://github.com/expressobits/inventory-system/blob/main/src/core/inventory.h"
click node_constraints "https://github.com/expressobits/inventory-system/blob/main/src/constraints/inventory_constraint.h"
click node_grid_inventory "https://github.com/expressobits/inventory-system/blob/main/src/core/grid_inventory.h"
click node_grid_constraints "https://github.com/expressobits/inventory-system/blob/main/src/constraints/grid_inventory_constraint.h"
click node_quad_tree "https://github.com/expressobits/inventory-system/blob/main/src/core/quad_tree.h"
click node_node_inventories "https://github.com/expressobits/inventory-system/blob/main/src/base/node_inventories.h"
click node_hotbar "https://github.com/expressobits/inventory-system/blob/main/src/core/hotbar.h"
click node_loot_generator "https://github.com/expressobits/inventory-system/blob/main/src/core/loot_generator.h"
click node_craft_station "https://github.com/expressobits/inventory-system/blob/main/src/craft/craft_station.h"
click node_editor_plugin "https://github.com/expressobits/inventory-system/blob/main/src/editor/inventory_editor_plugin.cpp"
click node_item_editor "https://github.com/expressobits/inventory-system/blob/main/src/editor/item_definition_editor.cpp"
click node_recipe_editor "https://github.com/expressobits/inventory-system/blob/main/src/editor/recipe_editor.cpp"
click node_loot_item_editor "https://github.com/expressobits/inventory-system/blob/main/src/editor/loot_item_editor.cpp"
click node_stack_selector "https://github.com/expressobits/inventory-system/blob/main/src/editor/item_stack_selector.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_item_definition,node_item_category,node_item_stack,node_recipe,node_station_type,node_loot,node_database toneBlue
class node_inventory,node_constraints,node_grid_inventory,node_grid_constraints,node_quad_tree,node_node_inventories toneAmber
class node_hotbar,node_loot_generator,node_craft_station toneMint
class node_editor_plugin,node_item_editor,node_recipe_editor,node_loot_item_editor,node_stack_selector toneRose
class node_actor toneIndigo
```

## Components

### Item resources

- [Item definitions](https://github.com/expressobits/inventory-system/blob/main/src/base/item_definition.h): `src/base/item_definition.h`
- [Item categories](https://github.com/expressobits/inventory-system/blob/main/src/base/item_category.h): `src/base/item_category.h`
- [Item stacks](https://github.com/expressobits/inventory-system/blob/main/src/base/item_stack.h): `src/base/item_stack.h`
- [Recipes](https://github.com/expressobits/inventory-system/blob/main/src/base/recipe.h): `src/base/recipe.h`
- [Station types](https://github.com/expressobits/inventory-system/blob/main/src/base/craft_station_type.h): `src/base/craft_station_type.h`
- [Loot resources](https://github.com/expressobits/inventory-system/blob/main/src/base/loot.h): `src/base/loot.h`
- [Inventory database](https://github.com/expressobits/inventory-system/blob/main/src/base/inventory_database.h): `src/base/inventory_database.h`

### Inventory runtime

- [Inventory](https://github.com/expressobits/inventory-system/blob/main/src/core/inventory.h): `src/core/inventory.h`
- [Inventory constraints](https://github.com/expressobits/inventory-system/blob/main/src/constraints/inventory_constraint.h): `src/constraints/inventory_constraint.h`
- [Grid inventory](https://github.com/expressobits/inventory-system/blob/main/src/core/grid_inventory.h): `src/core/grid_inventory.h`
- [Grid constraints](https://github.com/expressobits/inventory-system/blob/main/src/constraints/grid_inventory_constraint.h): `src/constraints/grid_inventory_constraint.h`
- [Grid spatial index](https://github.com/expressobits/inventory-system/blob/main/src/core/quad_tree.h): `src/core/quad_tree.h`
- [Node inventories](https://github.com/expressobits/inventory-system/blob/main/src/base/node_inventories.h): `src/base/node_inventories.h`

### Gameplay systems

- [Hotbar](https://github.com/expressobits/inventory-system/blob/main/src/core/hotbar.h): `src/core/hotbar.h`
- [Loot generator](https://github.com/expressobits/inventory-system/blob/main/src/core/loot_generator.h): `src/core/loot_generator.h`
- [Craft station](https://github.com/expressobits/inventory-system/blob/main/src/craft/craft_station.h): `src/craft/craft_station.h`

### Database editor

- [Inventory editor](https://github.com/expressobits/inventory-system/blob/main/src/editor/inventory_editor_plugin.cpp): `src/editor/inventory_editor_plugin.cpp`
- [Item editor](https://github.com/expressobits/inventory-system/blob/main/src/editor/item_definition_editor.cpp): `src/editor/item_definition_editor.cpp`
- [Recipe editor](https://github.com/expressobits/inventory-system/blob/main/src/editor/recipe_editor.cpp): `src/editor/recipe_editor.cpp`
- [Loot item editor](https://github.com/expressobits/inventory-system/blob/main/src/editor/loot_item_editor.cpp): `src/editor/loot_item_editor.cpp`
- [Stack selector](https://github.com/expressobits/inventory-system/blob/main/src/editor/item_stack_selector.h): `src/editor/item_stack_selector.h`

### Other components

- **Game logic**

## Connections

- Game logic → Inventory: manages items
- Inventory → Item stacks: stores stacks (evidence: `src/core/inventory.h`)
- Inventory → Inventory constraints: checks rules (evidence: `src/core/inventory.h`)
- Grid inventory → Inventory: extends (evidence: `src/core/grid_inventory.h`)
- Grid inventory → Grid spatial index: indexes spaces (evidence: `src/core/grid_inventory.h`)
- Grid inventory → Grid constraints: checks placement (evidence: `src/core/grid_inventory.h`)
- Node inventories → Inventory database: references (evidence: `src/base/node_inventories.h`)
- Node inventories → Item definitions: references (evidence: `src/base/node_inventories.h`)
- Hotbar → Inventory: uses inventory (evidence: `src/core/hotbar.h`)
- Hotbar → Node inventories: uses node inventories (evidence: `src/core/hotbar.h`)
- Inventory database → Item definitions: catalogs (evidence: `src/base/inventory_database.h`)
- Inventory database → Item categories: catalogs (evidence: `src/base/inventory_database.h`)
- Inventory database → Recipes: catalogs (evidence: `src/base/inventory_database.h`)
- Inventory database → Station types: catalogs (evidence: `src/base/inventory_database.h`)
- Inventory database → Loot resources: catalogs (evidence: `src/base/inventory_database.h`)
- Recipes → Station types: identifies station (evidence: `src/base/recipe.h`)
- Recipes → Item stacks: uses stacks (evidence: `src/base/recipe.h`)
- Loot resources → Loot item editor: edited by
- Craft station → Station types: uses type (evidence: `src/craft/craft_station.h`)
- Craft station → Inventory database: uses database (evidence: `src/craft/craft_station.h`)
- Craft station → Node inventories: inherits (evidence: `src/craft/craft_station.h`)
- Craft station → Inventory: uses inventories (evidence: `src/craft/craft_station.h`)
- Inventory editor → Inventory database: manages (evidence: `src/editor/inventory_editor_plugin.cpp`)
- Inventory editor → Recipe editor: opens editor (evidence: `src/editor/inventory_editor_plugin.cpp`)
- Inventory editor → Item editor: opens editor (evidence: `src/editor/inventory_editor_plugin.cpp`)
- Item editor → Inventory database: edits resources (evidence: `src/editor/item_definition_editor.cpp`)
- Item editor → Stack selector: uses selector (evidence: `src/editor/item_definition_editor.cpp`)
- Recipe editor → Inventory database: edits resources (evidence: `src/editor/recipe_editor.cpp`)
- Recipe editor → Stack selector: uses selector (evidence: `src/editor/recipe_editor.cpp`)
- Loot item editor → Inventory database: edits loot (evidence: `src/editor/loot_item_editor.cpp`)
- Loot item editor → Stack selector: uses selector (evidence: `src/editor/loot_item_editor.cpp`)
