Inventory System

Last Updated: 2025-01-16
Primary Source: docs/project_status.md
Service File: backend/src/services/inventory.service.ts
Model: backend/src/models/item.model.ts, backend/src/models/userInventory.model.ts

---

Overview

The Inventory System manages items and currency, creating a tangible in-game economy that connects player actions to rewards and enables item-based quest objectives.

---

Architecture

Inventory System Flow

---

Item Model

Item Table

Model: backend/src/models/item.model.ts

Fields:

• id - Primary key
• name - Item name
• description - Item description
• type - Item type (weapon, consumable, key, etc.)
• metadata - Additional item data (JSONB)

User Inventory Table

Model: backend/src/models/userInventory.model.ts

Fields:

• id - Primary key
• user_id - User ID
• item_id - Item ID
• quantity - Item quantity

Relationship: Many-to-many between Users and Items

---

Currency System

Energy Coins

Storage: users.energy_coins field

Purpose: In-game currency for transactions and rewards

Operations:

• Add coins (positive amount)
• Subtract coins (negative amount)
• Balance cannot go below 0

---

Inventory Service

Key Functions

getInventoryForUser(userId)

• Fetches complete inventory for user
• Includes item details
• Includes currency balance
• Returns formatted inventory object

modifyInventory(userId, itemId, quantity)

• Adds or removes items
• Quantity can be positive (add) or negative (remove)
• Creates inventory record if doesn't exist
• Removes record if quantity reaches 0
• Uses transactions for safety

modifyCurrency(userId, amount)

• Modifies energy coins balance
• Amount can be positive (add) or negative (subtract)
• Validates balance doesn't go negative
• Uses row locking for safety

---

AI Director Integration

Inventory Modification

Tool Command:

{
  "modifyInventory": {
    "itemId": 123,
    "quantity": 5
  }
}

Process:

1. AI Director decides to grant/consume item
2. Calls inventoryService.modifyInventory()
3. Item quantity updated
4. Timeline event created

Currency Modification

Tool Command:

{
  "modifyCurrency": {
    "amount": 100
  }
}

Process:

1. AI Director decides to grant/consume currency
2. Calls inventoryService.modifyCurrency()
3. Energy coins balance updated
4. Timeline event created

---

Inventory Context in Prompts

Inventory Summary

Service: backend/src/services/aso.service.ts

Function: summarizeInventoryForPrompt(inventory)

Format:

Inventory:
- Item Name (x5)
- Another Item (x2)

Energy Coins: 150

Usage: Included in ASO prompts so AI is "inventory-aware"

---

Data Flow

---

API Endpoints

Inventory Management

• GET /api/inventory - Get user inventory
• POST /api/inventory/modify - Modify inventory (admin)
• GET /api/items - List all items
• GET /api/items/:id - Get item details

---

Source Files

Primary Sources:

• backend/src/services/inventory.service.ts - Inventory management
• backend/src/models/item.model.ts - Item model
• backend/src/models/userInventory.model.ts - User inventory model

---

Related Documentation

• Quest System - Quest rewards (items and currency)
• AI Director - Inventory modification commands
• Tool System - Inventory tool implementation
• Timeline System - Inventory event tracking
• 06-ARCHITECTURE/Database-Schema.md - Inventory database schema
• 00-OVERVIEW.md - Complete system overview